Skip to main content
This reference documents webhook payloads and response examples for webhook notifications sent by the Quivo API. When you create a subscription for an entity type, Quivo sends HTTP POST requests to your configured endpoint when events occur for that entity.

​
Overview

When you subscribe to entity events using the Create Subscriptions guide, Quivo sends webhook notifications to your endpoint when specific events occur. Your endpoint receives these notifications as HTTP POST requests with JSON payloads containing event data.

​
Supported Entity Types

You can subscribe to webhook notifications for the following entity types:
Entity TypeDescriptionEvents Triggered
ORDERSOrder eventsOrder creation, status changes (for example, to PROCESSING)
SHIPMENTSShipment eventsShipment creation, tracking updates (for example, IN_TRANSIT, DELIVERED)
INBOUNDSInbound shipment eventsInbound shipment status changes
RETURNSReturn eventsWhen a return is created or received at the warehouse
INVOICESInvoice eventsInvoice creation and updates

​
Webhook Request Format

When an event occurs for a subscribed entity type, Quivo sends an HTTP POST request to your configured endpoint:
  • Method: POST
  • Content-Type: application/json
  • Body: JSON payload containing event data
Your endpoint must return a 200 OK HTTP status code to confirm receipt of the notification.
Your webhook endpoint must return a 200 OK response to confirm receipt of the notification. If your endpoint does not return 200 OK, Quivo may retry the webhook or mark it as failed.

​
Webhook Payload Structure

Webhook payloads follow a consistent structure across all entity types. The payload contains an events array with a single event object. Each event includes metadata about the entity that changed, but does not include the complete entity object.

​
Payload Format

{
  "events": [
    {
      "id": 123,
      "entity": "SHIPMENTS",
      "lastModified": "2019-12-15T14:48:12Z",
      "version": 2
    }
  ]
}
Event fields:
  • id (integer): The ID of the entity that changed
  • entity (string): The entity type (for example, ORDERS, SHIPMENTS, INBOUNDS, RETURNS, INVOICES)
  • lastModified (string): ISO 8601 timestamp of when the entity was last modified
  • version (integer): The version number of the entity
The webhook payload contains only the entity ID and metadata, not the complete entity object. To retrieve the full entity data, make a GET request to the appropriate endpoint using the id from the webhook payload.

​
Payload Examples by Entity Type

​
SHIPMENTS

{
  "events": [
    {
      "id": 123,
      "entity": "SHIPMENTS",
      "lastModified": "2019-12-15T14:48:12Z",
      "version": 2
    }
  ]
}

​
ORDERS

{
  "events": [
    {
      "id": 1923,
      "entity": "ORDERS",
      "lastModified": "2021-12-15T14:48:12Z",
      "version": 5
    }
  ]
}

​
INBOUNDS

{
  "events": [
    {
      "id": 1,
      "entity": "INBOUNDS",
      "lastModified": "2019-12-15T14:48:12Z",
      "version": 100
    }
  ]
}

​
RETURNS

{
  "events": [
    {
      "id": 1,
      "entity": "RETURNS",
      "lastModified": "2021-12-15T14:48:12Z",
      "version": 5
    }
  ]
}

​
INVOICES

The payload structure for INVOICES follows the same format as other entity types.

​
Webhook Headers

For EndpointWebhook type subscriptions:
  • Content-Type: application/json
  • No signature or signing: EndpointWebhook requests are unauthorized API POST requests (no authentication headers or signatures are included)
The Quivo API also supports AWS SNS/SQS events. For SNS events, the payload includes a subject field (for example, “UPDATE - ORDERS #9461772”). SQS events do not include a subject field.

​
Retrieving Full Entity Data

Since webhook payloads contain only the entity ID and metadata, you will need to retrieve the full entity data using the API:
  1. Extract the id and entity from the webhook payload
  2. Make a GET request to the appropriate endpoint:
    • For ORDERS: GET /orders/{id}
    • For SHIPMENTS: GET /shipments/{id}
    • For INBOUNDS: GET /inbounds/{id}
    • For RETURNS: GET /returns/{id}
    • For INVOICES: GET /invoices/{id}
Example: 
# Receive webhook with id: 1923, entity: "ORDERS"
# Then retrieve full order data:
curl -X GET "${BASE_URL}/orders/1923" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Authorization: <YOUR_SESSION_TOKEN>"

​
Where to go next

Now that you understand webhook notifications, continue with these guides:

Create Subscriptions

Learn how to create webhook subscriptions to receive event notifications.

Manage Subscriptions

Learn how to list and delete your webhook subscriptions.