Docs
Sign in

Configurations

Updated May 31, 20263 min read

A webhook configuration is your registered endpoint. It tells Carriyo where to POST events, which events should fire it, what conditions narrow when it fires, and how to authenticate the call.

Configurations are managed in the Dashboard under Settings → Webhooks. See the Configure a webhook how-to for a step-by-step walkthrough.

What a configuration includes

Every configuration carries:

  • Name. A descriptive label.
  • URL. Your endpoint.
  • Entity type. The entity whose events the webhook listens for: shipment, order, or return request.
  • Triggers. The specific events on the entity that fire the webhook.
  • Conditions. Optional filters that narrow when the webhook fires.
  • Authentication. Optional, configured per webhook. See Authentication.
  • Active flag. Toggle the webhook on or off without deleting it.

Triggers

A trigger is the specific event on the entity that fires the webhook. The trigger HTTP header on every delivery tells you which one fired. For shipment configurations the triggers are:

  • Status change — the shipment reaching a given status. The trigger header carries the status name itself (booked, error, in_transit, delivered, and so on). Subscribe to error to learn about failed bookings; the delivered Shipment's error_details[].source tells you whether Carriyo or the carrier rejected it (see Booking flow).
  • Reason-code change — certain reason codes are available as triggers, such as customs_cleared or customs_clearance_issue. When one fires, the trigger header carries the reason code.
  • Default label generated (default_label_update) — the shipment's default label is ready. This is the trigger to use for label-printing automation, not booked: the label isn't guaranteed to exist the instant the shipment books.
  • Carriyo label generated (carriyo_label_update) — the Carriyo-generated label specifically is ready.
  • Promised delivery date changed (promised_delivery_update).
  • Scheduled collection date changed (scheduled_collection_update).
  • Scheduled delivery date changed (scheduled_delivery_update).

For order and return-request configurations, triggers cover the lifecycle changes for that entity type.

The full set available for each entity type is shown in the Dashboard when configuring a webhook. See Authentication → headers Carriyo sends.

Conditions

Conditions narrow when a webhook fires within its triggers. A common use is "only fire for shipments going to the UK": the trigger is a status change, the condition narrows it to a specific destination.

Examples of conditions you can apply:

  • Pickup or dropoff country.
  • Pickup or dropoff postcode.
  • Delivery type or order type.
  • Custom conditions on tenant-defined attributes.

The Dashboard shows the full set of conditions available for the entity type when you're editing a webhook. Conditions on a single configuration are AND-combined; for OR-style logic across very different filter sets, create separate configurations.

Order webhook payload note

For shipment and return-request webhooks, the body of the delivery is the full entity object (Shipment or ReturnRequest). For order webhooks, the body is an envelope:

{
  "oldImage": { /* Order before the change */ },
  "newImage": { /* Order after the change */ },
  "trigger": "...",
  "operation": "..."
}

This is the only entity type that includes the before-and-after state in the payload.

Per-tenant cap

A per-tenant limit on the number of active webhook configurations may apply. If you're configuring many endpoints, check with your Carriyo contact.

If you need fan-out beyond your tenant cap, register one Carriyo webhook pointing at your own ingestion service. Fan out from there internally (queue or pub-sub) to as many downstream consumers as you need.

Visibility and history

The Dashboard shows each webhook's recent delivery history under Settings → Integration Monitor:

  • Recent events delivered.
  • Recent failures with HTTP status / response body.
  • Retry status for in-flight failed deliveries.
  • Replay actions for failed events.

This is the right place to investigate "my system stopped seeing events". The answer is usually a 5xx or timeout pattern visible in the delivery history.

How it fits with other modules