Skip to main content
WEBHOOK

Authorizations

Authorization
string
header
required

Token returned by POST /auth/token, sent as Authorization: Bearer <token>.

Headers

X-Webhook-Event
enum<string>
required

Name of the event (orderUpdated, orderFulfilled, shippingUpdated, inventoryMovement, replenishmentStatus, replenishmentCreated, replenishmentScheduled). Route on this header, not on the URL: all feeds can share one endpoint. Treat a request without this header as an order event.

Available options:
orderUpdated,
orderFulfilled,
shippingUpdated,
inventoryMovement,
replenishmentStatus,
replenishmentCreated,
replenishmentScheduled
X-Cubbo-Webhook-Message-Id
string<uuid>
required

UUID of this delivery attempt. It is part of the signed string. A new value is generated on every attempt, so a retry of the same event carries a different message id.

X-Cubbo-Hmac-SHA256
string
required

Lowercase hex HMAC-SHA256 of the string <message id>.<isa>.<exp>.<raw request body> computed with your webhook secret. Verify it against the exact bytes you received before parsing the body.

Pattern: ^[0-9a-f]{64}$
isa
string
required

Unix timestamp (seconds, UTC) at which the request was signed. Part of the signed string.

exp
string
required

Unix timestamp (seconds, UTC) after which the signature should be rejected; always isa + 300. Part of the signed string.

X-Cubbo-Idempotency-Key
string

Stable key for the event: identical on every retry of the same event. Sent on shippingUpdated (carrier tracking events), inventoryMovement and the replenishment events. Not sent on orderUpdated or orderFulfilled. Store the keys you have processed and ignore repeats.

Authorization
string

Bearer <token>, sent only when OAuth 2.0 client-credentials authentication has been configured for your integration by Cubbo. Cubbo requests the token from your token URL with grant_type=client_credentials and caches it until shortly before it expires.

Body

application/json

Payload of the shippingUpdated event.

status
enum<string>
required

Shipment status that triggered the event.

Available options:
shipment_in_transit,
shipment_out_for_delivery,
shipment_delivered,
shipment_partially_delivered,
shipment_with_incident,
shipment_returned,
shipment_canceled,
shipment_to_be_self_collected,
shipment_not_defined
Example:

"shipment_delivered"

store_id
integer
required

Cubbo store id.

Example:

1234

tracking_urls
string<uri>[]
required

Cubbo tracking page URL for the order (one element).

Example:
order_number
string
required

Your order number.

Example:

"ORD-0001"

updated_at
string<date-time>
required

Timestamp of the carrier tracking event.

Example:

"2026-10-14T18:32:10Z"

is_multi_package
boolean
required

Whether the order ships in more than one package.

Example:

false

packages
object[]
required

All packages of the order, oldest first.

carrier_name
string | null

Carrier of the package that triggered the event.

Example:

"Estafeta"

tracking_number
string | null

Carrier tracking number of the package that triggered the event.

Example:

"1234567890123456789012"

zip_code
string | null

Destination postal code ("-" for Chile shipments without one).

Example:

"06600"

estimated_time_arrival
string<date-time> | null

Estimated delivery date and time. null when the shipment was returned or reported stolen or lost.

Example:

"2026-10-14T23:59:59Z"

incident_description
enum<string> | null

Reason of the incident. Set only when status is shipment_with_incident.

Available options:
second_try,
third_try,
client_requested,
missing_references,
not_at_home,
refused_payment,
refused_package,
cubbo_requested,
carrier_requested,
stolen,
lost,
damaged,
loading_error,
pickup_expired,
delivery_failed,
null
Example:

null

label_tracking_event_id
integer | null

Id of the tracking event that produced this webhook. Stable across retries.

Example:

8812001

triggered_by_package
object

The package whose tracking event produced this webhook. Present when the event came from a specific package.

parent_order_id
integer

Present when this order is the child of a presale split; id of the original order.

Example:

987000

channel_name
string

Sales channel name given at creation, or the integration type when none was given.

Example:

"openapi"

channel_order_id
string

Your channel order id, when it was provided at creation.

Example:

"SHOP-77421"

channel_integration_id
integer

Cubbo integration id. Present only when channel details are enabled for your store.

Example:

4321

latest_estimated_time_arrival_range
object

Latest estimated delivery window, in UTC. Sent only when enabled for your integration; null when no estimate exists.

Response

2XX

Acknowledge receipt with any 2xx status. The response body is ignored. A 429 or any 5xx response is retried; any other 4xx response is treated as a permanent rejection and is not retried.