Webhook events

All deliveries share the same envelope:

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

charge.created

A merchant charge was created (still unpaid).

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

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

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

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

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

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

​Webhook events

​charge.created

​payment.succeeded

​charge.succeeded

​approval.required

​paylink.accepted

​budget.exhausted

​deposit.confirmed

​Delivery semantics