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

# Webhook events

> Every event type Payzor emits, with full payload examples and delivery semantics.

# Webhook events

All deliveries share the same envelope:

```json theme={null}
{
  "id": "evt_wh_9eab971e9e1a9bee",
  "type": "<event_type>",
  "createdAt": "2026-08-23T05:00:57.334Z",
  "data": { "...": "..." }
}
```

Headers: `X-Payzor-Event: <type>` and `X-Payzor-Signature: t=<unix_ts>,v1=<hex_hmac>`. Verification guide: [Webhooks](/guides/webhooks).

## charge.created

A merchant charge was created (still unpaid).

```json theme={null}
{
  "type": "charge.created",
  "data": {
    "chargeId": "chg_834e692669a3f8ad",
    "merchantId": "mch_c8fdac10d39c0c4d",
    "amountMinor": 200,
    "currency": "USD",
    "description": "API credits pack",
    "status": "pending",
    "merchantName": "Acme Digital Goods"
  }
}
```

## payment.succeeded

An agent paid from its wallet (directly, or via a PayLink draw). Money moved.

```json theme={null}
{
  "type": "payment.succeeded",
  "data": {
    "chargeId": "chg_834e692669a3f8ad",
    "amountMinor": 200,
    "currency": "USD",
    "merchantId": "mch_c8fdac10d39c0c4d",
    "agentId": "agent_6b75c0e895ba9c3d",
    "method": "ledger",
    "reference": "PAY_63FC9EDD0FAD129D"
  }
}
```

`method` is `ledger` (wallet) or `paylink` (budget draw). On-chain x402 settlements emit only `charge.succeeded`.

## charge.succeeded

The charge reached `paid`, whatever the method. Listen to this one if you only subscribe to a single event.

## approval.required

The paying agent's policy demanded human review. The money has **not** moved.

```json theme={null}
{
  "type": "approval.required",
  "data": {
    "approvalId": "apr_f097d968cdb81c8d",
    "agentId": "agent_6b75c0e895ba9c3d",
    "kind": "payment",
    "amount": 200,
    "reason": "Monto $200 supera umbral de aprobación humana ($30 USDC)",
    "expiresAt": "2026-08-23T05:01:45.143Z"
  }
}
```

If granted, you'll subsequently receive `charge.succeeded`. If it expires or is rejected, no further event fires for this charge; poll `GET /charges/:id` for final state.

## paylink.accepted

An agent accepted one of your PayLinks. The budget grant exists now.

```json theme={null}
{
  "type": "paylink.accepted",
  "data": {
    "grantId": "plg_8045a45414bdb863",
    "paylinkId": "pl_8eb56b59f563e9ed",
    "code": "h83YpjKQ",
    "agentId": "agent_6b75c0e895ba9c3d"
  }
}
```

## budget.exhausted

A PayLink's budget was fully drawn. Stop charging; issue a new link.

```json theme={null}
{
  "type": "budget.exhausted",
  "data": {
    "paylinkId": "pl_8eb56b59f563e9ed",
    "code": "h83YpjKQ",
    "spentMinor": 500
  }
}
```

## deposit.confirmed

On-chain USDC was detected and credited to an agent's wallet.

```json theme={null}
{
  "type": "deposit.confirmed",
  "data": {
    "agentId": "agent_xxx",
    "amount": 100000,
    "network": "base",
    "address": "0x..."
  }
}
```

## Delivery semantics

* **Retries**: non-2xx responses are retried with exponential backoff.
* **Ordering**: not guaranteed; dedupe by `id` and rely on `createdAt`.
* **Idempotency**: handlers should be safe to run twice for the same event.