Webhooks

The platform can notify your systems in real time whenever something important happens to a shipment or billing record. These notifications are called webhooks — outbound HTTP calls sent to a URL you configure.

Register one or more webhook endpoints through the API or the dashboard. Each endpoint is associated with a webhook type that determines which events it receives and what information is included.

Webhook types

Key benefits

• Real-time awareness — Learn about status changes and billing events as they happen, without polling.
• Flexible configuration — Register multiple endpoints for different event types.
• Security — v2 webhooks include HMAC-SHA256 signatures so you can verify that requests genuinely come from the platform.
• Reliability — v2 webhooks are delivered through a queue with automatic retries and deduplication, reducing the chance of missed or duplicate notifications.

Version differences (v1 vs v2)

• v1 (types 1 and 2) — Legacy format. Simple JSON body sent directly with optional Bearer-token authentication. Fire-and-forget delivery.
• v2 (types 3, 4, and 5) — Modern format. Standardized JSON envelope (type, created_at, data), HMAC-signed headers, queued delivery with retries and deduplication.

We recommend migrating from v1 to v2 for better security and reliability.

Payload reference

Type 1 — onShipmentStatusUpdate

Fires every time a shipment transitions to a new status (e.g. picked up, in transit, out for delivery, delivered, exception).

{
  "carrierName": "fedex",
  "trackingNumber": "100000",
  "status": "Delivered"
}

When to use: Basic integrations that only need carrier, tracking number, and current status. No order or e-commerce context.

Type 2 — statusUpdateWithEcommerceInfo

Same trigger as type 1 — any shipment status change — but the payload includes e-commerce order information.

orderData fields:

{
  "carrierName": "Paquetexpress",
  "trackingNumber": "123456789",
  "status": "Delivered",
  "movementDate": null,
  "orderData": {
    "shopId": 12345,
    "orderIdentifier": "2345678923456-1",
    "orderNumber": "2345678923456",
    "orderName": "923456"
  }
}

When to use: E-commerce integrations that need to match shipment events back to specific store orders. Recommended over type 1 when order correlation is required.

If the shipment record is missing order_number or order_name, the system automatically looks them up before sending.

Type 3 — simpleTracking

Same trigger as type 1 — shipment status change — but uses v2 infrastructure.

{
  "type": "tracking.simple",
  "created_at": "2025-01-15T10:30:00.000Z",
  "data": {
    "shipment_id": 12345,
    "tracking_number": "ABC123",
    "status": "Delivered",
    "carrier_name": "fedex"
  }
}

v2 HTTP headers:

When to use: Recommended replacement for type 1. Same shipment data but with signature verification, reliable delivery, and a standardized envelope.

Type 4 — ecommerceTracking

Same trigger as type 2 — shipment status change for e-commerce orders — using v2 infrastructure.

order_data fields:

{
  "type": "tracking.ecommerce",
  "created_at": "2025-01-15T10:30:00.000Z",
  "data": {
    "shipment_id": 12345,
    "tracking_number": "ABC123",
    "status": "Delivered",
    "carrier_name": "fedex",
    "order_data": {
      "shop_id": 12345,
      "order_identifier": "2345678923456-1",
      "order_number": "2345678923456",
      "order_name": "923456"
    }
  }
}

When to use: Recommended replacement for type 2. E-commerce integrations that need order context with v2 security and reliability.

If the shipment record is missing order_number or order_name, the system automatically looks them up before sending.

v2 uses snake_case (order_data, shop_id) while v1 uses camelCase (orderData, shopId).

Type 5 — surcharge

Fires when a surcharge (extra charge) or refund is applied to a shipment.

surcharge_data fields:

{
  "type": "surcharge",
  "created_at": "2025-01-15T10:30:00.000Z",
  "data": {
    "surcharge_id": 100,
    "shipment_id": 12345,
    "tracking_number": "ABC123",
    "carrier_name": "fedex",
    "surcharge_data": {
      "surcharge_type": "Overweight",
      "reason": "Package exceeded weight limit",
      "amount": 150.00,
      "currency": "MXN",
      "transaction_type": "surcharge"
    }
  }
}

When to use: Billing and finance integrations that need real-time notification of extra charges or refunds applied to shipments.

Each surcharge notification uses a unique event ID for deduplication, so the same surcharge can be delivered to multiple endpoints without duplicates.

Comparison matrix