Skip to main content
WEBHOOK
A single subscription to parcels.event.created delivers two unrelated response shapes, selected by data.event.event_type:
The two shapes do not share fields beyond event_type and timestamp — in particular, phase and sub_status are different enums on each shape. Always check event.event_type first and parse the rest of event according to that value; do not assume a tracking field (e.g. exception) is present on a claim event, or vice versa.

Parsing the payload

Whatever language you use, the approach is the same:
  1. Read data.event.event_type.
  2. Pick the model: carrier, calculated or internal → Tracking Event; claim → Claim Event.
  3. Parse data.event with that model. Treat phase, sub_status, category, resolution and origin as plain strings, because new values can be added at any time.

Identifying the parcel

  • data.parcel.parcel_id: the Sendcloud tracking parcel ID. It is not the Shipping API parcel ID.
  • data.parcel.source_id: the parcel ID in the source system. The value depends on data.parcel.source:
    • shipping: the Shipping API parcel ID.
    • external_parcel: the ID you sent when you registered the parcel with the Parcel Tracking API.
  • Do not use source_id as a unique key. When a carrier uses a tracking number again, two parcels can have the same source_id.

Internal events

  • Events with event_type internal come from Sendcloud, not from the carrier.
  • Examples: announcing, announced, ready to send, cancelled.
  • An internal event can arrive before the parcel.created event for the same parcel.

Events sent again

Sendcloud can send the same carrier event more than one time.
  • event.id stays the same for each copy. For internal and calculated events, event.id is null.
  • The data can change between copies. When you get an event.id that you already have, replace the earlier copy.
  • Example: a carrier sends a status code that Sendcloud does not know yet. Sendcloud sends the event with an unknown status. When Sendcloud maps the status code, it sends the event again with the correct status. Sendcloud does this only for carrier events from the last 7 days.

Body

application/json

Event data delivered to your endpoint

Event payload delivered to your endpoint when a parcel tracking event occurs.

event_type
enum<string>
required

The event type identifier.

Available options:
parcels.event.created
Example:

"parcels.event.created"

data
object
required

The event payload.

Response

200

Return a 2xx status to acknowledge receipt of the event.