> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.quivo.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook Response Examples

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](/docs/webhooks/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 Type | Description             | Events Triggered                                                             |
| ----------- | ----------------------- | ---------------------------------------------------------------------------- |
| `ORDERS`    | Order events            | Order creation, status changes (for example, to `PROCESSING`)                |
| `SHIPMENTS` | Shipment events         | Shipment creation, tracking updates (for example, `IN_TRANSIT`, `DELIVERED`) |
| `INBOUNDS`  | Inbound shipment events | Inbound shipment status changes                                              |
| `RETURNS`   | Return events           | When a return is created or received at the warehouse                        |
| `INVOICES`  | Invoice events          | Invoice 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.

<Warning>
  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.
</Warning>

## 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

```json theme={null}
{
  "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

<Note>
  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.
</Note>

## Payload Examples by Entity Type

### SHIPMENTS

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

### ORDERS

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

### INBOUNDS

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

### RETURNS

```json theme={null}
{
  "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)

<Note>
  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.
</Note>

## 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:**

```bash theme={null}
# 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:

<CardGroup cols={2}>
  <Card title="Create Subscriptions" icon="plus" href="/docs/webhooks/create-subscriptions">
    Learn how to create webhook subscriptions to receive event notifications.
  </Card>

  <Card title="Manage Subscriptions" icon="settings" href="/docs/webhooks/manage-subscriptions">
    Learn how to list and delete your webhook subscriptions.
  </Card>
</CardGroup>