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

# Payload and headers

> The structure of every webhook request: the JSON envelope, HTTP headers and data conventions

## Request

Every delivery is an HTTPS `POST` with a JSON body.

```http theme={null}
POST /webhooks/pazy HTTP/1.1
Content-Type: application/json
User-Agent: Pazy-Webhook-Delivery/1.0
X-Pazy-Webhook-Timestamp: 1746873600
X-Pazy-Webhook-Signature: sha256=9f67d39dcd1132a50c4d57d9770b32c31ce8e76268f9eb6dd4e73af7f44b9c59
X-Pazy-Webhook-Attempt: 1
X-Pazy-Webhook-Subscription-Id: 6b1f2d0e-5c1a-4a39-9f0e-2f9d6a7c1b11
```

## Headers

| Header | Example | Description |
| - | - | - |
| `Content-Type` | `application/json` | Always `application/json` |
| `User-Agent` | `Pazy-Webhook-Delivery/1.0` | Identifies Pazy's delivery service. The version part can change |
| `X-Pazy-Webhook-Timestamp` | `1746873600` | Unix time in seconds when this attempt was signed |
| `X-Pazy-Webhook-Signature` | `sha256=bdb11c…` | HMAC-SHA256 signature of the request. See [Verify signatures](/webhooks/verify-signatures) |
| `X-Pazy-Webhook-Attempt` | `1` | Delivery attempt number, from 1 to 5 |
| `X-Pazy-Webhook-Subscription-Id` | `6b1f2d0e-…` | The subscription that matched this event |

Header names are case-insensitive. Read them in whatever form your framework exposes.

<Note>
  Every attempt, including a retry, is signed again with a fresh timestamp. A retry is never rejected by the 5-minute timestamp check just because the original event is old.
</Note>

## Event envelope

The body has the same five fields for every event type.

```json theme={null}
{
  "id": "018f1a2b-3c4d-7e8f-9a0b-1c2d3e4f5a6d",
  "type": "payment.invoice.completed",
  "version": "1",
  "createdAt": "2026-08-10T09:14:21.000Z",
  "data": {
    "paymentId": "8841203",
    "transactionId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "source": "PLATFORM",
    "resource": { "id": "inv_8fk21ma", "identifier": "INV-4471" },
    "amount": "1234.50",
    "currency": "INR",
    "utr": "UTR123456789",
    "paymentDate": "2026-08-10T09:14:20.000Z",
    "isFinalSettlement": true,
    "paymentRequestId": "pr_2kd9",
    "originalTransactionId": null
  }
}
```

| Field | Type | Description |
| - | - | - |
| `id` | string (UUID) | Unique identifier of the event. It stays the same across retries, so use it to [deduplicate](/webhooks/delivery-and-retries#handle-duplicates) |
| `type` | string | The event type, such as `payment.invoice.completed`. See the [event reference](/webhooks/events/overview) |
| `version` | string | Payload schema version. Currently `"1"` |
| `createdAt` | string (ISO 8601) | When the event was recorded, in UTC |
| `data` | object | The event-specific fields. Each event type documents its own `data` |

## Data conventions

These apply across the event reference, unless a page says otherwise.

| Convention | Detail |
| - | - |
| Timestamps | ISO 8601 in UTC with milliseconds, for example `2026-05-10T12:00:00.000Z` |
| Money | Decimal **strings** with two places, such as `"1234.50"`, so you never lose precision |
| Currency | ISO 4217 three-letter code, such as `INR` |
| Nullable fields | Documented as nullable when the value can be `null`. The key is still present |
| `metadata` | An open-ended object. New keys can appear at any time, so don't reject unknown keys |
| Naming | `camelCase`, except the `payout.api.transaction.status_changed` event, which uses `snake_case` to match the Payouts API |

## Forward compatibility

Pazy can add new fields to `data`, new keys inside `metadata`, and new event types without a version change. Build your handler to tolerate them:

* Ignore fields you don't use.
* Return `2xx` for event types you don't handle, so Pazy doesn't retry them.
* Don't fail on enum values you haven't seen, such as a new `status`. Fall back to a safe default.

A breaking change to a payload would ship under a new `version` value.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.