Configurations
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 guide 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, return request, or inventory.
- Triggers. The specific events on the entity that fire the webhook.
- Conditions. Optional filters that narrow when the webhook fires (not available for all entity types).
- 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. The available triggers depend on the entity
type.
Shipment webhooks support 27 triggers across status changes, metadata changes (label generation, scheduling), and reason codes. See Shipment webhook events for the full catalogue.
Order webhooks support 18 triggers covering order-level and fulfillment-order lifecycle events. See Order webhook events for the full catalogue.
Return request webhooks support 8 status triggers and 2
item-level triggers. The trigger header carries
return_status_update or return_received_update. See
Return webhook events
for the full catalogue.
Inventory webhooks have a single trigger,
ALL_INVENTORY_UPDATES, covering all stock mutations. See
Inventory webhook events
for details.
Payload shapes
The payload format depends on the entity type. Your handler should be tolerant of unknown fields — Carriyo adds new fields over time.
- Shipment: the full Shipment object as JSON. No wrapper. See Shipment webhook events.
- Order: an envelope with
oldImage/newImage(camelCase),trigger, andoperation. See Order webhook events. - Return request: the full ReturnRequest object as JSON. No wrapper. See Return webhook events.
- Inventory: an envelope with
old_image/new_image(snake_case),trigger, andoperation. See Inventory webhook events.
The order and inventory envelopes use different casing.
Orders use camelCase (oldImage, newImage); inventory uses
snake_case (old_image, new_image). Handle both if you
subscribe to multiple entity types.
Conditions
Conditions narrow when a webhook fires within its triggers. They are AND-combined: all must match for the webhook to fire. For OR-style logic, create separate configurations.
Available conditions vary by entity type:
Shipment conditions
| Condition | What it filters |
|---|---|
| Shipment type | Forward, reverse, or consolidated |
| Delivery type | Home delivery, click-and-collect, etc. |
| Dropoff geography | Destination country, state, city, area, or postcode |
| Pickup location | Specific origin locations |
| Creation source type | How the shipment was created (API, connector, Dashboard) |
Order conditions
| Condition | What it filters |
|---|---|
| Creation source type | How the order was created (API, connector, Dashboard) |
Return request conditions
No entity-specific conditions beyond merchant. The webhook fires for all return-request events matching the configured triggers.
Inventory conditions
No conditions available. The webhook fires for every stock change across the entire tenant. If you need to filter by product or location, implement that logic in your handler.
Inventory webhooks are tenant-scoped (not merchant-scoped), so a single configuration receives changes for all products across all locations in the tenant.
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
- Webhooks. The parent module.
- Authentication. Configured per webhook.
- Retry and idempotency. How delivery handles failures.