Webhooks

Webhooks allow you to receive real-time notifications when events occur in your cargopanel account. Instead of polling the API for updates, webhooks push data to your application as events happen.

Authentication: All webhook management endpoints require API Key authentication. Include your API key in the request headers.

How It Works

1. Create a subscription — Register a URL and choose the events you want to listen to.

2. Receive events — When an event occurs, cargopanel sends an HTTP POST request to your registered URL with the event payload.

3. Verify signature — Each delivery includes an X-Webhook-Signature header for payload verification.

4. Respond with 2xx — Return a 2xx status code to acknowledge receipt. Failed deliveries are retried automatically.

Supported Events

Event	Description
`shipment.status.updated`	Fired when a shipment's status changes.
`shipment.milestone.updated`	Fired when a shipment reaches a new milestone.

Webhook Payload

{
  "event": "shipment.status.updated",
  "shipmentId": "12345678",
  "carrier": "UPS",
  "trackingNumber": "1Z999AA10123456784",
  "userId": "usr_xyz789",
 "previousStatus": {
    "status": "Package is sorted, waiting for delivery.",
    "description": "Package is sorted, waiting for delivery.",
    "location": "Germany",
    "date": "2026-05-19T13:50:00+0300",
    "milestone": "in_transit"
  },
  "currentStatus": {
    "status": "Package is arrived post office/facility",
    "description": "Package is arrived post office/facility",
    "location": "Germany",
    "date": "2026-05-22T12:14:00+0300",
    "milestone": "in_transit"
  },
  "updatedAt": "2026-06-20T14:30:00.000Z"
}

Delivery Headers

Header	Description
`X-Webhook-Signature`	HMAC-SHA256 signature of the payload using your subscription secret.
`X-Webhook-Timestamp`	Unix timestamp of when the event was sent.
`X-Webhook-Event`	The event type (e.g. `shipment.status.updated`).
`X-Webhook-Delivery-Id`	Unique delivery ID for idempotency.

Retry Policy

If your endpoint returns a non-2xx response or is unreachable, cargopanel will retry the delivery using an exponential backoff strategy:

Parameter	Default
Max retries	5
Initial delay	10 seconds
Backoff multiplier	2x (exponential)
Max delay	1 hour

After all retries are exhausted, the delivery is moved to the dead letter queue.

Error Codes

Create Subscription