> ## 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.

# Eventos de webhook

> Todos los tipos de evento que emite Payzor, con ejemplos completos de carga y semántica de entrega.

# Eventos de webhook

Todas las entregas comparten el mismo sobre:

```json theme={null}
{
  "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](/es/guides/webhooks).

## charge.created

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

```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

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

```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` 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.

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

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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.