Eventos de webhook

Todas las entregas comparten el mismo sobre:

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

Cabeceras: X-Payzor-Event: <type> y X-Payzor-Signature: t=<unix_ts>,v1=<hex_hmac>. Guía de verificación: Webhooks.

charge.created

Se creó un cargo de comercio (todavía sin pagar).

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

Un agente pagó desde su billetera (directamente, o mediante un cobro de PayLink). El dinero se movió.

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

method es ledger (billetera) o paylink (cobro contra presupuesto). Las liquidaciones x402 on-chain emiten solo charge.succeeded.

charge.succeeded

El cargo llegó a paid, sea cual sea el método. Suscríbete a este si solo vas a escuchar un evento.

approval.required

La política del agente que paga exigió revisión humana. El dinero no se ha movido.

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

Si se concede, después recibirás charge.succeeded. Si caduca o se rechaza, no se dispara ningún evento más para ese cargo; consulta GET /charges/:id para el estado final.

paylink.accepted

Un agente aceptó uno de tus PayLinks. El grant de presupuesto ya existe.

{
  "type": "paylink.accepted",
  "data": {
    "grantId": "plg_8045a45414bdb863",
    "paylinkId": "pl_8eb56b59f563e9ed",
    "code": "h83YpjKQ",
    "agentId": "agent_6b75c0e895ba9c3d"
  }
}

budget.exhausted

El presupuesto de un PayLink se consumió por completo. Deja de cobrar; emite un link nuevo.

{
  "type": "budget.exhausted",
  "data": {
    "paylinkId": "pl_8eb56b59f563e9ed",
    "code": "h83YpjKQ",
    "spentMinor": 500
  }
}

deposit.confirmed

Se detectó USDC on-chain y se acreditó a la billetera de un agente.

{
  "type": "deposit.confirmed",
  "data": {
    "agentId": "agent_xxx",
    "amount": 100000,
    "network": "base",
    "address": "0x..."
  }
}

Semántica de entrega

Reintentos: las respuestas que no son 2xx se reintentan con backoff exponencial.
Orden: no está garantizado; deduplica por id y apóyate en createdAt.
Idempotencia: tus handlers deberían poder ejecutarse dos veces con el mismo evento sin efectos raros.

​Eventos de webhook

​charge.created

​payment.succeeded

​charge.succeeded

​approval.required

​paylink.accepted

​budget.exhausted

​deposit.confirmed

​Semántica de entrega