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

# Payloads

> The structure of a webhook request from Zivio

### Request format

Zivio delivers each event as an HTTP `POST` request to your configured URL with a JSON body and a `Content-Type` of `application/json`. Requests are sent with the user agent `Zivio-Webhooks/1.0`.

### Headers

Every request includes the following headers, which you use to [verify the signature](/webhooks/verifying-signatures):

<ResponseField name="webhook-id" type="string">
  A unique identifier for this event. Use it to de-duplicate events if your endpoint might receive the same delivery more than once.
</ResponseField>

<ResponseField name="webhook-timestamp" type="string">
  The time the event was sent, as a Unix timestamp (seconds).
</ResponseField>

<ResponseField name="webhook-signature" type="string">
  The signature(s) for this request, used to confirm it came from Zivio. See [Verifying Signatures](/webhooks/verifying-signatures).
</ResponseField>

### Payload structure

The JSON body follows a consistent envelope:

<ResponseField name="id" type="string">
  The unique identifier for the event. This matches the `webhook-id` header.
</ResponseField>

<ResponseField name="type" type="string">
  The event type, such as `invoice.paid`. See [Event Types](/webhooks/event-types).
</ResponseField>

<ResponseField name="occurred_at" type="string">
  An ISO 8601 timestamp for when the event occurred.
</ResponseField>

<ResponseField name="api_version" type="string">
  The API version that shapes the `data` object — currently `v4`.
</ResponseField>

<ResponseField name="data" type="object">
  The resource the event relates to, serialized exactly as it would be returned by the equivalent [v4 API](/api-reference) endpoint. The fields included reflect the permissions of the webhook's owner.
</ResponseField>

### Example payload

```json theme={null}
{
  "id": "evt_a1b2c3d4e5f6",
  "type": "invoice.paid",
  "occurred_at": "2026-06-10T14:32:05Z",
  "api_version": "v4",
  "data": {
    "id": 12345,
    "status": "paid"
    // ...the rest of the invoice, matching the v4 Invoices API
  }
}
```

<Tip>To know exactly which fields appear in `data` for a given event, look up the matching resource in the [API Reference](/api-reference). For example, an `invoice.*` event's `data` mirrors the [Invoices](/api-reference/invoices/retrieve-an-invoice-by-id) response.</Tip>

### Test event payload

A manually triggered test event uses the type `webhook.test` and a placeholder body, so you can validate your endpoint without referencing real data:

```json theme={null}
{
  "id": "evt_test_0000",
  "type": "webhook.test",
  "occurred_at": "2026-06-10T14:32:05Z",
  "api_version": "v4",
  "data": { "test": true }
}
```

### Responding to a request

Your endpoint should:

* Return a `2xx` status code to acknowledge successful receipt.
* Respond quickly — requests time out after **30 seconds**. If your processing is slow, acknowledge the request first and do the work asynchronously.
* Treat delivery as **at-least-once**: the same event may occasionally arrive more than once. De-duplicate using the `webhook-id` / `id` value.

Any non-`2xx` response (or a timeout) is treated as a failed delivery and may be [retried](/webhooks/delivery-and-retries).