# Webhooks

This webhook documentation is currently available only in the `v1.preview`
channel and may change before general availability.

Ingrid webhooks provide server-to-server event notifications when orders or
parcels are updated in Ingrid.

This documentation includes:

- the webhook payload reference
- guidance for receiving and acknowledging deliveries
- current retry behavior
- the public events catalog that can trigger a delivery
- request verification guidance for signed webhook requests
- replay-prevention guidance for freshness and deduplication


## Delivery model

Each delivery uses a shared event envelope with:

- `id` as the unique event identifier
- `createdAt` as the event timestamp
- `triggerName` as the configured trigger scenario that matched
- `triggeringEvent` as the public catalog event that caused the webhook
- `data` as the order or parcel payload


`triggeringEvent` identifies the underlying event. `triggerName` identifies the
configured trigger scenario that caused the receiver to be notified.

For example:

- `triggeringEvent: order.confirmed.v1`
- `triggerName: us-order-confirmed`


This means the underlying event was `order.confirmed.v1`, and the delivery was
sent because the configured `us-order-confirmed` scenario matched.

```json
{
  "$ref": "#/components/schemas/BaseEvent",
  "components": {
    "schemas": {
      "BaseEvent": {
        "type": "object",
        "description": "Common webhook delivery fields",
        "required": [
          "id",
          "createdAt",
          "triggerName",
          "triggeringEvent"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique delivery identifier. Use this for idempotency and deduplication."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the webhook delivery was created."
          },
          "triggerName": {
            "type": "string",
            "description": "Name of the configured trigger that generated the delivery."
          },
          "triggeringEvent": {
            "type": "string",
            "description": "Public business event that caused the webhook delivery."
          }
        }
      }
    }
  }
}
```

There are currently two payload families:

- `OrderEvent` for order-level notifications
- `ParcelEvent` for parcel-level notifications


## Events catalog

Webhook deliveries are triggered by a public Ingrid event exposed in the
top-level `triggeringEvent` field.

Refer to [Events Catalog](/developer-resources/ingrid-api/webhooks/events) for the list of supported events and
their meaning.

## Payload shapes

### Order events

```json
{
  "$ref": "#/components/schemas/EcomOrderEvent",
  "components": {
    "schemas": {
      "BaseEvent": {
        "type": "object",
        "description": "Common webhook delivery fields",
        "required": [
          "id",
          "createdAt",
          "triggerName",
          "triggeringEvent"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique delivery identifier. Use this for idempotency and deduplication."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the webhook delivery was created."
          },
          "triggerName": {
            "type": "string",
            "description": "Name of the configured trigger that generated the delivery."
          },
          "triggeringEvent": {
            "type": "string",
            "description": "Public business event that caused the webhook delivery."
          }
        }
      },
      "OrderPublicEventType": {
        "type": "string",
        "description": "Event type that caused the webhook.",
        "oneOf": [
          {
            "const": "order.confirmed.v1",
            "description": "Published when an order is confirmed."
          },
          {
            "const": "order.withdrawal_submitted.v1",
            "description": "Published when a withdrawal of one or more order items is submitted by the customer."
          }
        ]
      },
      "EcomOrderMeta": {
        "type": "object",
        "description": "E-commerce order metadata with counts and versioning",
        "required": [
          "version",
          "fulfillments_count",
          "parcels_count"
        ],
        "properties": {
          "version": {
            "type": "integer",
            "format": "int64",
            "description": "E-commerce order version number"
          },
          "fulfillments_count": {
            "type": "integer",
            "format": "int32",
            "description": "Number of fulfillments"
          },
          "parcels_count": {
            "type": "integer",
            "format": "int32",
            "description": "Number of parcels"
          }
        }
      },
      "DisplayAttribute": {
        "type": "object",
        "description": "Display-oriented key/value attribute for a cart item",
        "required": [
          "key",
          "value"
        ],
        "properties": {
          "key": {
            "type": "string",
            "description": "Stable identifier for the attribute"
          },
          "value": {
            "type": "string",
            "description": "Displayable value"
          },
          "label": {
            "type": "string",
            "description": "Human-readable label"
          }
        }
      },
      "CartItem": {
        "type": "object",
        "description": "Individual item in a shopping cart",
        "properties": {
          "sku": {
            "type": "string",
            "description": "Stock Keeping Unit identifier"
          },
          "name": {
            "type": "string",
            "description": "Product name or title"
          },
          "quantity": {
            "type": "integer",
            "format": "int32",
            "minimum": 0,
            "description": "Number of non-cancelled items"
          },
          "price": {
            "type": "integer",
            "format": "int32",
            "description": "Price per item with discounts applied in cents"
          },
          "discount": {
            "type": "integer",
            "format": "int32",
            "description": "Discount per item in cents"
          },
          "total_price": {
            "type": "integer",
            "format": "int32",
            "description": "Total price for all non-cancelled items in cents"
          },
          "image": {
            "type": "string",
            "format": "uri",
            "description": "URL of the product image"
          },
          "cancelled_quantity": {
            "type": "integer",
            "format": "int32",
            "minimum": 0,
            "description": "Number of cancelled items"
          },
          "cancelled_total_price": {
            "type": "integer",
            "format": "int32",
            "description": "Total price for cancelled items in cents"
          },
          "attributes": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Additional item properties as key-value pairs"
          },
          "display_attributes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DisplayAttribute"
            },
            "description": "Display-oriented attributes for the item (key/value/label)"
          }
        }
      },
      "Cart": {
        "type": "object",
        "description": "Shopping cart with items and pricing",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CartItem"
            },
            "description": "List of items in the cart"
          },
          "order_discount": {
            "type": "integer",
            "format": "int32",
            "description": "Order discount in cents"
          },
          "shipping_price": {
            "type": "integer",
            "format": "int32",
            "description": "Shipping price in cents"
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$",
            "description": "Currency code (ISO-4217)"
          },
          "total_discount": {
            "type": "integer",
            "format": "int32",
            "description": "Total discount amount in cents"
          },
          "tax": {
            "type": "integer",
            "format": "int32",
            "description": "Tax amount in cents"
          },
          "subtotal": {
            "type": "integer",
            "format": "int32",
            "description": "Subtotal before additional charges in cents"
          },
          "grand_total": {
            "type": "integer",
            "format": "int32",
            "description": "Final amount to pay in cents"
          },
          "attributes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Custom attributes for the cart"
          }
        }
      },
      "PaymentEntry": {
        "type": "object",
        "description": "Individual payment entry with method and amount",
        "required": [
          "method",
          "amount",
          "currency"
        ],
        "properties": {
          "method": {
            "type": "string",
            "description": "Payment method used"
          },
          "amount": {
            "type": "integer",
            "format": "int32",
            "description": "Payment amount in cents"
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$",
            "description": "Currency code (ISO-4217)"
          },
          "attributes": {
            "type": "object",
            "additionalProperties": true,
            "description": "Additional payment attributes"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "Payment timestamp"
          }
        }
      },
      "PaymentStatus": {
        "type": "string",
        "description": "Status of payment transaction",
        "enum": [
          "SUCCESS",
          "FAILURE"
        ]
      },
      "Payment": {
        "type": "object",
        "description": "Payment information with entries and status",
        "required": [
          "status"
        ],
        "properties": {
          "entries": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PaymentEntry"
            },
            "description": "List of payment entries"
          },
          "status": {
            "$ref": "#/components/schemas/PaymentStatus"
          }
        }
      },
      "Coordinates": {
        "type": "object",
        "description": "Geographical coordinates",
        "required": [
          "lat",
          "lng"
        ],
        "properties": {
          "lat": {
            "type": "number",
            "format": "double",
            "minimum": -90,
            "maximum": 90,
            "description": "Latitude"
          },
          "lng": {
            "type": "number",
            "format": "double",
            "minimum": -180,
            "maximum": 180,
            "description": "Longitude"
          }
        }
      },
      "Address": {
        "type": "object",
        "description": "Complete address information with geolocation",
        "properties": {
          "name": {
            "type": "string",
            "description": "Customer or company name"
          },
          "care_of": {
            "type": "string",
            "description": "Care of part of address (c/o)"
          },
          "attn": {
            "type": "string",
            "description": "Attention field for company addresses"
          },
          "address_lines": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Address lines including street and building number"
          },
          "city": {
            "type": "string",
            "description": "City name"
          },
          "region": {
            "type": "string",
            "description": "State or province"
          },
          "postal_code": {
            "type": "string",
            "description": "Postal code or zipcode"
          },
          "country": {
            "type": "string",
            "pattern": "^[A-Z]{2}$",
            "description": "Country code (ISO Alpha-2)"
          },
          "coordinates": {
            "$ref": "#/components/schemas/Coordinates"
          },
          "door_code": {
            "type": "string",
            "description": "Door code for building entrance"
          },
          "street": {
            "type": "string",
            "description": "Street name"
          },
          "street_number": {
            "type": "string",
            "description": "Street number"
          },
          "apartment_number": {
            "type": "string",
            "description": "Apartment number"
          },
          "floor_number": {
            "type": "string",
            "description": "Floor number"
          },
          "subregion": {
            "type": "string",
            "description": "County or other subdivision"
          },
          "building_name": {
            "type": "string",
            "description": "Building name (for UK addresses without numbers)"
          },
          "po_box_id": {
            "type": "string",
            "description": "PO Box identifier"
          }
        }
      },
      "CancellingParty": {
        "type": "string",
        "description": "Party that cancelled the order",
        "enum": [
          "UNKNOWN",
          "MERCHANT",
          "CUSTOMER"
        ]
      },
      "EcomOrderData": {
        "type": "object",
        "description": "Core e-commerce order data without fulfillments and parcels arrays",
        "required": [
          "id",
          "tos_id",
          "created_at",
          "meta"
        ],
        "properties": {
          "meta": {
            "$ref": "#/components/schemas/EcomOrderMeta"
          },
          "tos_id": {
            "type": "string",
            "description": "TOS identifier"
          },
          "id": {
            "type": "string",
            "description": "External order ID"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Order creation timestamp"
          },
          "cart": {
            "$ref": "#/components/schemas/Cart"
          },
          "payment": {
            "$ref": "#/components/schemas/Payment"
          },
          "locale": {
            "type": "string",
            "description": "Order locale"
          },
          "attributes": {
            "type": "object",
            "additionalProperties": true,
            "description": "Additional order attributes"
          },
          "billing_address": {
            "$ref": "#/components/schemas/Address"
          },
          "tracking_link": {
            "type": "string",
            "format": "uri",
            "description": "Order tracking link"
          },
          "is_cancelled": {
            "type": "boolean",
            "description": "Indicates if the order has been cancelled"
          },
          "is_estimated_preparation_time_exceeded": {
            "type": "boolean",
            "description": "Indicates if the estimated preparation time has been exceeded"
          },
          "cancelled_by": {
            "$ref": "#/components/schemas/CancellingParty"
          }
        }
      },
      "ContactInfo": {
        "type": "object",
        "description": "Contact details including address, phone, and email",
        "properties": {
          "address": {
            "$ref": "#/components/schemas/Address"
          },
          "phone": {
            "type": "string",
            "description": "Phone number"
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "Email address"
          },
          "name": {
            "type": "string",
            "description": "Full name"
          }
        }
      },
      "Receiver": {
        "type": "object",
        "description": "Buyer information with contact and billing details",
        "required": [
          "contact_info",
          "billing"
        ],
        "properties": {
          "contact_info": {
            "$ref": "#/components/schemas/ContactInfo"
          },
          "billing": {
            "$ref": "#/components/schemas/ContactInfo"
          }
        }
      },
      "ShippingPickupLocationType": {
        "type": "string",
        "description": "Type of pickup location for shipping",
        "enum": [
          "UNKNOWN",
          "LOCKER",
          "STORE",
          "POSTOFFICE",
          "MANNED"
        ]
      },
      "OperationalHours": {
        "type": "object",
        "description": "Weekly operational hours for each day",
        "properties": {
          "mon": {
            "type": "string",
            "description": "Monday operational hours"
          },
          "tue": {
            "type": "string",
            "description": "Tuesday operational hours"
          },
          "wed": {
            "type": "string",
            "description": "Wednesday operational hours"
          },
          "thu": {
            "type": "string",
            "description": "Thursday operational hours"
          },
          "fri": {
            "type": "string",
            "description": "Friday operational hours"
          },
          "sat": {
            "type": "string",
            "description": "Saturday operational hours"
          },
          "sun": {
            "type": "string",
            "description": "Sunday operational hours"
          },
          "free_text": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Free text operational hours as fallback"
          }
        }
      },
      "PickupPointDetails": {
        "type": "object",
        "description": "Details about pickup point location",
        "properties": {
          "location_ref": {
            "type": "string",
            "description": "Reference identifier for the location"
          },
          "location_type": {
            "$ref": "#/components/schemas/ShippingPickupLocationType"
          },
          "operational_hours": {
            "$ref": "#/components/schemas/OperationalHours"
          }
        }
      },
      "Location": {
        "type": "object",
        "description": "Location information with address and pickup details",
        "properties": {
          "address": {
            "$ref": "#/components/schemas/Address"
          },
          "courier_instructions": {
            "type": "string",
            "description": "Special instructions for courier"
          },
          "pickup_point_details": {
            "$ref": "#/components/schemas/PickupPointDetails"
          }
        }
      },
      "CarrierInfo": {
        "type": "object",
        "description": "Information about shipping carrier",
        "properties": {
          "carrier_name": {
            "type": "string",
            "description": "Name of the carrier company"
          },
          "carrier_product_id": {
            "type": "string",
            "description": "Carrier's product identifier"
          },
          "carrier_product_ref": {
            "type": "string",
            "description": "Carrier's product reference"
          },
          "carrier_logo_pattern": {
            "type": "string",
            "description": "Pattern for carrier logo URL"
          }
        }
      },
      "DateTimeRange": {
        "type": "object",
        "description": "Time range with start and end timestamps",
        "properties": {
          "start": {
            "type": "string",
            "format": "date-time",
            "description": "Start time of the range"
          },
          "end": {
            "type": "string",
            "format": "date-time",
            "description": "End time of the range"
          }
        }
      },
      "DeliveryPromise": {
        "type": "object",
        "description": "Delivery time promises and ranges",
        "properties": {
          "pickup_from_merchant": {
            "$ref": "#/components/schemas/DateTimeRange"
          },
          "customer_delivery_promise": {
            "$ref": "#/components/schemas/DateTimeRange"
          },
          "carrier_delivery_promise": {
            "$ref": "#/components/schemas/DateTimeRange"
          }
        }
      },
      "Shipping": {
        "type": "object",
        "description": "Shipping information including carrier and delivery promise",
        "properties": {
          "carrier_info": {
            "$ref": "#/components/schemas/CarrierInfo"
          },
          "delivery_promise": {
            "$ref": "#/components/schemas/DeliveryPromise"
          }
        }
      },
      "DeliveryType": {
        "type": "string",
        "description": "Type of delivery method",
        "enum": [
          "UNKNOWN",
          "DELIVERY",
          "PICKUP",
          "MAILBOX",
          "INSTORE",
          "INWAREHOUSE"
        ]
      },
      "TrackingStep": {
        "type": "string",
        "description": "Current step in the tracking process",
        "enum": [
          "STEP_UNKNOWN",
          "STEP_CONFIRMED_BY_MERCHANT",
          "STEP_PREPARED_BY_MERCHANT",
          "STEP_SUBMITTED_TO_CARRIER",
          "STEP_ON_ROUTE",
          "STEP_DELIVERED_TO_PICKUP_POINT",
          "STEP_DELIVERED_TO_CONSUMER",
          "STEP_TERMINATED",
          "STEP_SENT_BACK",
          "STEP_RETURN_REQUESTED",
          "STEP_DELIVERED_TO_MERCHANT",
          "STEP_AWAITING_SUPPLIER",
          "STEP_LINEHAUL_TO_CARRIER"
        ]
      },
      "Fulfillment": {
        "type": "object",
        "description": "Order fulfillment with shipping and delivery details",
        "required": [
          "tos_id",
          "sender",
          "receiver",
          "destination",
          "delivery_type",
          "current_step"
        ],
        "properties": {
          "attributes": {
            "type": "object",
            "additionalProperties": true,
            "description": "Additional fulfillment attributes"
          },
          "tos_id": {
            "type": "string",
            "description": "TOS identifier"
          },
          "sender": {
            "$ref": "#/components/schemas/ContactInfo"
          },
          "receiver": {
            "$ref": "#/components/schemas/Receiver"
          },
          "destination": {
            "$ref": "#/components/schemas/Location"
          },
          "shipping": {
            "$ref": "#/components/schemas/Shipping"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CartItem"
            },
            "description": "Items in this fulfillment"
          },
          "shipping_method": {
            "type": "string",
            "description": "Shipping method name"
          },
          "delivery_type": {
            "$ref": "#/components/schemas/DeliveryType"
          },
          "current_step": {
            "$ref": "#/components/schemas/TrackingStep"
          },
          "is_submission_time_exceeded": {
            "type": "boolean",
            "description": "Indicates if the submission time has been exceeded"
          },
          "is_cancelled": {
            "type": "boolean",
            "description": "Indicates if the fulfillment has been cancelled"
          },
          "is_delivery_time_exceeded": {
            "type": "boolean",
            "description": "Indicates if the delivery time has been exceeded"
          }
        }
      },
      "RefusalReason": {
        "type": "string",
        "description": "Reason for parcel refusal",
        "enum": [
          "UNKNOWN",
          "NO_REASON",
          "NOT_ORDERED",
          "GOODS_DAMAGED",
          "PACKAGING_DAMAGED"
        ]
      },
      "ParcelData": {
        "type": "object",
        "description": "Core parcel data without associated order",
        "required": [
          "tos_id",
          "tracking_number"
        ],
        "properties": {
          "tos_id": {
            "type": "string",
            "description": "TOS identifier"
          },
          "carrier_info": {
            "$ref": "#/components/schemas/CarrierInfo"
          },
          "delivery_promise": {
            "$ref": "#/components/schemas/DeliveryPromise"
          },
          "delivery_type": {
            "$ref": "#/components/schemas/DeliveryType"
          },
          "sender_address": {
            "$ref": "#/components/schemas/Address"
          },
          "sender_name": {
            "type": "string",
            "description": "Sender name"
          },
          "customer": {
            "$ref": "#/components/schemas/ContactInfo"
          },
          "destination": {
            "$ref": "#/components/schemas/Location"
          },
          "tracking_number": {
            "type": "string",
            "description": "Parcel tracking number"
          },
          "tracking_link": {
            "type": "string",
            "format": "uri",
            "description": "Parcel tracking link"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CartItem"
            },
            "description": "List of items in the parcel"
          },
          "current_step": {
            "$ref": "#/components/schemas/TrackingStep"
          },
          "attributes": {
            "type": "object",
            "additionalProperties": true,
            "description": "Additional parcel attributes"
          },
          "is_estimated_delivery_time_exceeded": {
            "type": "boolean",
            "description": "Indicates if the estimated delivery time has been exceeded"
          },
          "is_delayed": {
            "type": "boolean",
            "description": "Indicates if the delivery is delayed"
          },
          "is_out_for_delivery": {
            "type": "boolean",
            "description": "Indicates if the parcel is out for delivery"
          },
          "out_for_delivery_at": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the parcel was marked as out for delivery"
          },
          "failed_delivery_attempts_count": {
            "type": "integer",
            "format": "int32",
            "description": "Number of failed delivery attempts"
          },
          "last_failed_delivery_attempt_at": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp of the last failed delivery attempt"
          },
          "is_refused": {
            "type": "boolean",
            "description": "Indicates if the parcel was refused by the recipient"
          },
          "refusal_reason": {
            "$ref": "#/components/schemas/RefusalReason"
          },
          "is_overdue": {
            "type": "boolean",
            "description": "When true, parcel is confirmed overdue for pickup. False doesn't guarantee it's not overdue."
          }
        }
      },
      "EcomOrder": {
        "type": "object",
        "description": "Complete e-commerce order model with fulfillments and parcels",
        "allOf": [
          {
            "$ref": "#/components/schemas/EcomOrderData"
          },
          {
            "type": "object",
            "properties": {
              "fulfillments": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/Fulfillment"
                }
              },
              "parcels": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ParcelData"
                }
              }
            }
          }
        ]
      },
      "EcomOrderEvent": {
        "type": "object",
        "description": "Webhook delivery containing the e-commerce order payload model.",
        "allOf": [
          {
            "$ref": "#/components/schemas/BaseEvent"
          },
          {
            "type": "object",
            "description": "Webhook delivery where `data` uses the `EcomOrder` schema.",
            "required": [
              "type",
              "triggeringEvent",
              "data"
            ],
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "ECOM_ORDER"
                ],
                "description": "Payload model type for the `data` object."
              },
              "triggeringEvent": {
                "$ref": "#/components/schemas/OrderPublicEventType"
              },
              "data": {
                "$ref": "#/components/schemas/EcomOrder"
              }
            }
          }
        ]
      }
    }
  }
}
```

### Parcel events

```json
{
  "$ref": "#/components/schemas/ParcelEvent",
  "components": {
    "schemas": {
      "BaseEvent": {
        "type": "object",
        "description": "Common webhook delivery fields",
        "required": [
          "id",
          "createdAt",
          "triggerName",
          "triggeringEvent"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique delivery identifier. Use this for idempotency and deduplication."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the webhook delivery was created."
          },
          "triggerName": {
            "type": "string",
            "description": "Name of the configured trigger that generated the delivery."
          },
          "triggeringEvent": {
            "type": "string",
            "description": "Public business event that caused the webhook delivery."
          }
        }
      },
      "ParcelPublicEventType": {
        "type": "string",
        "description": "Event type that caused the webhook.",
        "oneOf": [
          {
            "const": "parcel.prepared_by_merchant.v1",
            "description": "Published when parcel progress changes to Prepared by Merchant."
          },
          {
            "const": "parcel.submitted_to_carrier.v1",
            "description": "Published when parcel progress changes to Submitted to Carrier."
          },
          {
            "const": "parcel.delivered_to_pickup_point.v1",
            "description": "Published when parcel progress changes to Delivered to Pickup Point."
          },
          {
            "const": "parcel.delivered_to_consumer.v1",
            "description": "Published when parcel progress changes to Delivered to Consumer."
          },
          {
            "const": "parcel.terminated.v1",
            "description": "Published when parcel progress changes to Terminated because delivery can no longer be completed."
          },
          {
            "const": "parcel.sent_back.v1",
            "description": "Published when parcel progress changes to Sent Back and the parcel is returning to the sender."
          },
          {
            "const": "parcel.on_route.v1",
            "description": "Published when parcel progress changes to On Route."
          },
          {
            "const": "parcel.out_for_delivery.v1",
            "description": "Published when the carrier marks the parcel as out for final-mile delivery."
          },
          {
            "const": "parcel.delivery_attempt_failed.v1",
            "description": "Published when a delivery attempt fails."
          },
          {
            "const": "parcel.delivery_delayed.v1",
            "description": "Published when the carrier reports that delivery is delayed."
          },
          {
            "const": "parcel.estimated_delivery_time_updated.v1",
            "description": "Published when the parcel ETA is updated."
          },
          {
            "const": "parcel.estimated_delivery_time_exceeded.v1",
            "description": "Published when the current parcel ETA is exceeded."
          }
        ]
      },
      "CarrierInfo": {
        "type": "object",
        "description": "Information about shipping carrier",
        "properties": {
          "carrier_name": {
            "type": "string",
            "description": "Name of the carrier company"
          },
          "carrier_product_id": {
            "type": "string",
            "description": "Carrier's product identifier"
          },
          "carrier_product_ref": {
            "type": "string",
            "description": "Carrier's product reference"
          },
          "carrier_logo_pattern": {
            "type": "string",
            "description": "Pattern for carrier logo URL"
          }
        }
      },
      "DateTimeRange": {
        "type": "object",
        "description": "Time range with start and end timestamps",
        "properties": {
          "start": {
            "type": "string",
            "format": "date-time",
            "description": "Start time of the range"
          },
          "end": {
            "type": "string",
            "format": "date-time",
            "description": "End time of the range"
          }
        }
      },
      "DeliveryPromise": {
        "type": "object",
        "description": "Delivery time promises and ranges",
        "properties": {
          "pickup_from_merchant": {
            "$ref": "#/components/schemas/DateTimeRange"
          },
          "customer_delivery_promise": {
            "$ref": "#/components/schemas/DateTimeRange"
          },
          "carrier_delivery_promise": {
            "$ref": "#/components/schemas/DateTimeRange"
          }
        }
      },
      "DeliveryType": {
        "type": "string",
        "description": "Type of delivery method",
        "enum": [
          "UNKNOWN",
          "DELIVERY",
          "PICKUP",
          "MAILBOX",
          "INSTORE",
          "INWAREHOUSE"
        ]
      },
      "Coordinates": {
        "type": "object",
        "description": "Geographical coordinates",
        "required": [
          "lat",
          "lng"
        ],
        "properties": {
          "lat": {
            "type": "number",
            "format": "double",
            "minimum": -90,
            "maximum": 90,
            "description": "Latitude"
          },
          "lng": {
            "type": "number",
            "format": "double",
            "minimum": -180,
            "maximum": 180,
            "description": "Longitude"
          }
        }
      },
      "Address": {
        "type": "object",
        "description": "Complete address information with geolocation",
        "properties": {
          "name": {
            "type": "string",
            "description": "Customer or company name"
          },
          "care_of": {
            "type": "string",
            "description": "Care of part of address (c/o)"
          },
          "attn": {
            "type": "string",
            "description": "Attention field for company addresses"
          },
          "address_lines": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Address lines including street and building number"
          },
          "city": {
            "type": "string",
            "description": "City name"
          },
          "region": {
            "type": "string",
            "description": "State or province"
          },
          "postal_code": {
            "type": "string",
            "description": "Postal code or zipcode"
          },
          "country": {
            "type": "string",
            "pattern": "^[A-Z]{2}$",
            "description": "Country code (ISO Alpha-2)"
          },
          "coordinates": {
            "$ref": "#/components/schemas/Coordinates"
          },
          "door_code": {
            "type": "string",
            "description": "Door code for building entrance"
          },
          "street": {
            "type": "string",
            "description": "Street name"
          },
          "street_number": {
            "type": "string",
            "description": "Street number"
          },
          "apartment_number": {
            "type": "string",
            "description": "Apartment number"
          },
          "floor_number": {
            "type": "string",
            "description": "Floor number"
          },
          "subregion": {
            "type": "string",
            "description": "County or other subdivision"
          },
          "building_name": {
            "type": "string",
            "description": "Building name (for UK addresses without numbers)"
          },
          "po_box_id": {
            "type": "string",
            "description": "PO Box identifier"
          }
        }
      },
      "ContactInfo": {
        "type": "object",
        "description": "Contact details including address, phone, and email",
        "properties": {
          "address": {
            "$ref": "#/components/schemas/Address"
          },
          "phone": {
            "type": "string",
            "description": "Phone number"
          },
          "email": {
            "type": "string",
            "format": "email",
            "description": "Email address"
          },
          "name": {
            "type": "string",
            "description": "Full name"
          }
        }
      },
      "ShippingPickupLocationType": {
        "type": "string",
        "description": "Type of pickup location for shipping",
        "enum": [
          "UNKNOWN",
          "LOCKER",
          "STORE",
          "POSTOFFICE",
          "MANNED"
        ]
      },
      "OperationalHours": {
        "type": "object",
        "description": "Weekly operational hours for each day",
        "properties": {
          "mon": {
            "type": "string",
            "description": "Monday operational hours"
          },
          "tue": {
            "type": "string",
            "description": "Tuesday operational hours"
          },
          "wed": {
            "type": "string",
            "description": "Wednesday operational hours"
          },
          "thu": {
            "type": "string",
            "description": "Thursday operational hours"
          },
          "fri": {
            "type": "string",
            "description": "Friday operational hours"
          },
          "sat": {
            "type": "string",
            "description": "Saturday operational hours"
          },
          "sun": {
            "type": "string",
            "description": "Sunday operational hours"
          },
          "free_text": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Free text operational hours as fallback"
          }
        }
      },
      "PickupPointDetails": {
        "type": "object",
        "description": "Details about pickup point location",
        "properties": {
          "location_ref": {
            "type": "string",
            "description": "Reference identifier for the location"
          },
          "location_type": {
            "$ref": "#/components/schemas/ShippingPickupLocationType"
          },
          "operational_hours": {
            "$ref": "#/components/schemas/OperationalHours"
          }
        }
      },
      "Location": {
        "type": "object",
        "description": "Location information with address and pickup details",
        "properties": {
          "address": {
            "$ref": "#/components/schemas/Address"
          },
          "courier_instructions": {
            "type": "string",
            "description": "Special instructions for courier"
          },
          "pickup_point_details": {
            "$ref": "#/components/schemas/PickupPointDetails"
          }
        }
      },
      "DisplayAttribute": {
        "type": "object",
        "description": "Display-oriented key/value attribute for a cart item",
        "required": [
          "key",
          "value"
        ],
        "properties": {
          "key": {
            "type": "string",
            "description": "Stable identifier for the attribute"
          },
          "value": {
            "type": "string",
            "description": "Displayable value"
          },
          "label": {
            "type": "string",
            "description": "Human-readable label"
          }
        }
      },
      "CartItem": {
        "type": "object",
        "description": "Individual item in a shopping cart",
        "properties": {
          "sku": {
            "type": "string",
            "description": "Stock Keeping Unit identifier"
          },
          "name": {
            "type": "string",
            "description": "Product name or title"
          },
          "quantity": {
            "type": "integer",
            "format": "int32",
            "minimum": 0,
            "description": "Number of non-cancelled items"
          },
          "price": {
            "type": "integer",
            "format": "int32",
            "description": "Price per item with discounts applied in cents"
          },
          "discount": {
            "type": "integer",
            "format": "int32",
            "description": "Discount per item in cents"
          },
          "total_price": {
            "type": "integer",
            "format": "int32",
            "description": "Total price for all non-cancelled items in cents"
          },
          "image": {
            "type": "string",
            "format": "uri",
            "description": "URL of the product image"
          },
          "cancelled_quantity": {
            "type": "integer",
            "format": "int32",
            "minimum": 0,
            "description": "Number of cancelled items"
          },
          "cancelled_total_price": {
            "type": "integer",
            "format": "int32",
            "description": "Total price for cancelled items in cents"
          },
          "attributes": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            },
            "description": "Additional item properties as key-value pairs"
          },
          "display_attributes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/DisplayAttribute"
            },
            "description": "Display-oriented attributes for the item (key/value/label)"
          }
        }
      },
      "TrackingStep": {
        "type": "string",
        "description": "Current step in the tracking process",
        "enum": [
          "STEP_UNKNOWN",
          "STEP_CONFIRMED_BY_MERCHANT",
          "STEP_PREPARED_BY_MERCHANT",
          "STEP_SUBMITTED_TO_CARRIER",
          "STEP_ON_ROUTE",
          "STEP_DELIVERED_TO_PICKUP_POINT",
          "STEP_DELIVERED_TO_CONSUMER",
          "STEP_TERMINATED",
          "STEP_SENT_BACK",
          "STEP_RETURN_REQUESTED",
          "STEP_DELIVERED_TO_MERCHANT",
          "STEP_AWAITING_SUPPLIER",
          "STEP_LINEHAUL_TO_CARRIER"
        ]
      },
      "RefusalReason": {
        "type": "string",
        "description": "Reason for parcel refusal",
        "enum": [
          "UNKNOWN",
          "NO_REASON",
          "NOT_ORDERED",
          "GOODS_DAMAGED",
          "PACKAGING_DAMAGED"
        ]
      },
      "ParcelData": {
        "type": "object",
        "description": "Core parcel data without associated order",
        "required": [
          "tos_id",
          "tracking_number"
        ],
        "properties": {
          "tos_id": {
            "type": "string",
            "description": "TOS identifier"
          },
          "carrier_info": {
            "$ref": "#/components/schemas/CarrierInfo"
          },
          "delivery_promise": {
            "$ref": "#/components/schemas/DeliveryPromise"
          },
          "delivery_type": {
            "$ref": "#/components/schemas/DeliveryType"
          },
          "sender_address": {
            "$ref": "#/components/schemas/Address"
          },
          "sender_name": {
            "type": "string",
            "description": "Sender name"
          },
          "customer": {
            "$ref": "#/components/schemas/ContactInfo"
          },
          "destination": {
            "$ref": "#/components/schemas/Location"
          },
          "tracking_number": {
            "type": "string",
            "description": "Parcel tracking number"
          },
          "tracking_link": {
            "type": "string",
            "format": "uri",
            "description": "Parcel tracking link"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CartItem"
            },
            "description": "List of items in the parcel"
          },
          "current_step": {
            "$ref": "#/components/schemas/TrackingStep"
          },
          "attributes": {
            "type": "object",
            "additionalProperties": true,
            "description": "Additional parcel attributes"
          },
          "is_estimated_delivery_time_exceeded": {
            "type": "boolean",
            "description": "Indicates if the estimated delivery time has been exceeded"
          },
          "is_delayed": {
            "type": "boolean",
            "description": "Indicates if the delivery is delayed"
          },
          "is_out_for_delivery": {
            "type": "boolean",
            "description": "Indicates if the parcel is out for delivery"
          },
          "out_for_delivery_at": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp when the parcel was marked as out for delivery"
          },
          "failed_delivery_attempts_count": {
            "type": "integer",
            "format": "int32",
            "description": "Number of failed delivery attempts"
          },
          "last_failed_delivery_attempt_at": {
            "type": "string",
            "format": "date-time",
            "description": "Timestamp of the last failed delivery attempt"
          },
          "is_refused": {
            "type": "boolean",
            "description": "Indicates if the parcel was refused by the recipient"
          },
          "refusal_reason": {
            "$ref": "#/components/schemas/RefusalReason"
          },
          "is_overdue": {
            "type": "boolean",
            "description": "When true, parcel is confirmed overdue for pickup. False doesn't guarantee it's not overdue."
          }
        }
      },
      "EcomOrderMeta": {
        "type": "object",
        "description": "E-commerce order metadata with counts and versioning",
        "required": [
          "version",
          "fulfillments_count",
          "parcels_count"
        ],
        "properties": {
          "version": {
            "type": "integer",
            "format": "int64",
            "description": "E-commerce order version number"
          },
          "fulfillments_count": {
            "type": "integer",
            "format": "int32",
            "description": "Number of fulfillments"
          },
          "parcels_count": {
            "type": "integer",
            "format": "int32",
            "description": "Number of parcels"
          }
        }
      },
      "Cart": {
        "type": "object",
        "description": "Shopping cart with items and pricing",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CartItem"
            },
            "description": "List of items in the cart"
          },
          "order_discount": {
            "type": "integer",
            "format": "int32",
            "description": "Order discount in cents"
          },
          "shipping_price": {
            "type": "integer",
            "format": "int32",
            "description": "Shipping price in cents"
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$",
            "description": "Currency code (ISO-4217)"
          },
          "total_discount": {
            "type": "integer",
            "format": "int32",
            "description": "Total discount amount in cents"
          },
          "tax": {
            "type": "integer",
            "format": "int32",
            "description": "Tax amount in cents"
          },
          "subtotal": {
            "type": "integer",
            "format": "int32",
            "description": "Subtotal before additional charges in cents"
          },
          "grand_total": {
            "type": "integer",
            "format": "int32",
            "description": "Final amount to pay in cents"
          },
          "attributes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Custom attributes for the cart"
          }
        }
      },
      "PaymentEntry": {
        "type": "object",
        "description": "Individual payment entry with method and amount",
        "required": [
          "method",
          "amount",
          "currency"
        ],
        "properties": {
          "method": {
            "type": "string",
            "description": "Payment method used"
          },
          "amount": {
            "type": "integer",
            "format": "int32",
            "description": "Payment amount in cents"
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$",
            "description": "Currency code (ISO-4217)"
          },
          "attributes": {
            "type": "object",
            "additionalProperties": true,
            "description": "Additional payment attributes"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "Payment timestamp"
          }
        }
      },
      "PaymentStatus": {
        "type": "string",
        "description": "Status of payment transaction",
        "enum": [
          "SUCCESS",
          "FAILURE"
        ]
      },
      "Payment": {
        "type": "object",
        "description": "Payment information with entries and status",
        "required": [
          "status"
        ],
        "properties": {
          "entries": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PaymentEntry"
            },
            "description": "List of payment entries"
          },
          "status": {
            "$ref": "#/components/schemas/PaymentStatus"
          }
        }
      },
      "CancellingParty": {
        "type": "string",
        "description": "Party that cancelled the order",
        "enum": [
          "UNKNOWN",
          "MERCHANT",
          "CUSTOMER"
        ]
      },
      "EcomOrderData": {
        "type": "object",
        "description": "Core e-commerce order data without fulfillments and parcels arrays",
        "required": [
          "id",
          "tos_id",
          "created_at",
          "meta"
        ],
        "properties": {
          "meta": {
            "$ref": "#/components/schemas/EcomOrderMeta"
          },
          "tos_id": {
            "type": "string",
            "description": "TOS identifier"
          },
          "id": {
            "type": "string",
            "description": "External order ID"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "Order creation timestamp"
          },
          "cart": {
            "$ref": "#/components/schemas/Cart"
          },
          "payment": {
            "$ref": "#/components/schemas/Payment"
          },
          "locale": {
            "type": "string",
            "description": "Order locale"
          },
          "attributes": {
            "type": "object",
            "additionalProperties": true,
            "description": "Additional order attributes"
          },
          "billing_address": {
            "$ref": "#/components/schemas/Address"
          },
          "tracking_link": {
            "type": "string",
            "format": "uri",
            "description": "Order tracking link"
          },
          "is_cancelled": {
            "type": "boolean",
            "description": "Indicates if the order has been cancelled"
          },
          "is_estimated_preparation_time_exceeded": {
            "type": "boolean",
            "description": "Indicates if the estimated preparation time has been exceeded"
          },
          "cancelled_by": {
            "$ref": "#/components/schemas/CancellingParty"
          }
        }
      },
      "Parcel": {
        "type": "object",
        "description": "Parcel model with associated order data",
        "required": [
          "tos_id",
          "tracking_number",
          "order"
        ],
        "allOf": [
          {
            "$ref": "#/components/schemas/ParcelData"
          },
          {
            "type": "object",
            "properties": {
              "order": {
                "$ref": "#/components/schemas/EcomOrderData"
              }
            }
          }
        ]
      },
      "ParcelEvent": {
        "type": "object",
        "description": "Webhook delivery containing the parcel payload model.",
        "allOf": [
          {
            "$ref": "#/components/schemas/BaseEvent"
          },
          {
            "type": "object",
            "description": "Webhook delivery where `data` uses the `Parcel` schema.",
            "required": [
              "type",
              "triggeringEvent",
              "data"
            ],
            "properties": {
              "type": {
                "type": "string",
                "enum": [
                  "PARCEL"
                ],
                "description": "Payload model type for the `data` object."
              },
              "triggeringEvent": {
                "$ref": "#/components/schemas/ParcelPublicEventType"
              },
              "data": {
                "$ref": "#/components/schemas/Parcel"
              }
            }
          }
        ]
      }
    }
  }
}
```

## Where to go next

- [API Reference](/developer-resources/ingrid-api/v1.preview/openapi) for the full webhook contract
- [Getting Started](/developer-resources/ingrid-api/webhooks/integration) for receiver design and acknowledgment flow
- [Verifying Requests](/developer-resources/ingrid-api/webhooks/verifying-requests) for signing and signature validation
- [Replay Prevention](/developer-resources/ingrid-api/webhooks/replay-prevention) for freshness checks and deduplication
- [Delivery and Retries](/developer-resources/ingrid-api/webhooks/delivery-and-retries) for success and retry semantics
- [Events Catalog](/developer-resources/ingrid-api/webhooks/events) for the supported event catalog