Skip to main content

​
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:
​
webhook-id
string
A unique identifier for this event. Use it to de-duplicate events if your endpoint might receive the same delivery more than once.
​
webhook-timestamp
string
The time the event was sent, as a Unix timestamp (seconds).
​
webhook-signature
string
The signature(s) for this request, used to confirm it came from Zivio. See Verifying Signatures.

​
Payload structure

The JSON body follows a consistent envelope:
​
id
string
The unique identifier for the event. This matches the webhook-id header.
​
type
string
The event type, such as invoice.paid. See Event Types.
​
occurred_at
string
An ISO 8601 timestamp for when the event occurred.
​
api_version
string
The API version that shapes the data object — currently v4.
​
data
object
The resource the event relates to, serialized exactly as it would be returned by the equivalent v4 API endpoint. The fields included reflect the permissions of the webhook’s owner.

​
Example payload

{
  "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
  }
}
To know exactly which fields appear in data for a given event, look up the matching resource in the API Reference. For example, an invoice.* event’s data mirrors the Invoices response.

​
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: 
{
  "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.