Webhook events

The events we send, what each one carries, and how retries work.

Embed
Preview of the card
<a href="https://forumulate.com/p/trackified/docs/events"><img src="https://forumulate.com/api/public/orgs/trackified/spaces/docs/pages/ea5b2bb8-fc57-4d9a-9ec1-4eb9ccd0c8a2/social-card.svg?v=3e7ae33eec8b" alt="Webhook events" width="600" height="315"></a>

Register an endpoint with POST /v1/webhooks and pick the events you want in event_types.

A tracking's status is one of not_yet_scanned, in_transit, out_for_delivery, delivered, exception, returned or unknown. returned means the carrier is sending the parcel back (return to sender), told apart from other exceptions.

Event

Sent when

tracking.created

A tracking is added.

tracking.updated

We checked the carrier and saved the result. data is the tracking.

tracking.status_changed

The status changes, for example from in_transit to out_for_delivery. data has tracking, previous_status and current_status.

tracking.delivered

The parcel is delivered.

tracking.exception

The carrier reports a problem (a failed delivery, a hold), or we couldn't reach the carrier on this check.

tracking.returned

The parcel is being returned to its sender. The tracking's status becomes returned.

Every delivery is a POST with a JSON body:

{
  "id": "evt_...",
  "type": "tracking.status_changed",
  "created_at": "2026-10-21T20:18:19.402Z",
  "data": {
    "tracking": { "id": "trk_...", "tracking_number": "1Z999AA10123456784", "status": "out_for_delivery", "events": [] },
    "previous_status": "in_transit",
    "current_status": "out_for_delivery"
  }
}

Retries

Answer with any 2xx status once you've accepted the event. Anything else, or no answer, and we try again: up to 5 attempts, about 30 seconds apart. An endpoint that fails 100 times in a row is disabled; turn it back on in the dashboard once it's fixed.

Use the event id to ignore an event you've already handled. To test your handler, POST /v1/webhooks/{id}/test returns a signed sample event without sending it.

Updated