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

# Webhooks

> Reciba notificaciones en tiempo real para pagos, violaciones de políticas y eventos de agentes.

## Descripción general

Los webhooks entregan notificaciones de eventos en tiempo real a su aplicación mediante solicitudes HTTP POST. Úselos para reaccionar a pagos, violaciones de políticas, cambios de estado de agentes y eventos de sesiones x402.

## Configuración de webhooks

### Mediante SDK

```typescript theme={null}
const webhook = await aw.webhooks.create({
  url: "https://your-app.com/webhooks/agentwallex",
  events: [
    "payment.completed",
    "payment.failed",
    "agent.frozen",
    "policy.violated",
  ],
  secret: "whsec_your_signing_secret",
});
```

### Mediante API

```bash theme={null}
curl -X POST https://api.agentwallex.com/api/v1/webhooks \
  -H "X-API-Key: awx_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/agentwallex",
    "events": ["payment.completed", "payment.failed", "agent.frozen", "policy.violated"],
    "secret": "whsec_your_signing_secret"
  }'
```

## Tipos de eventos

| Evento                 | Descripción                                              |
| ---------------------- | -------------------------------------------------------- |
| `payment.completed`    | Transacción confirmada on-chain                          |
| `payment.failed`       | Transacción fallida o revertida                          |
| `payment.pending`      | Transacción enviada, esperando confirmación              |
| `agent.frozen`         | Billetera del agente fue congelada                       |
| `agent.unfrozen`       | Billetera del agente fue descongelada                    |
| `policy.violated`      | Transacción rechazada por el motor de políticas          |
| `x402.session.expired` | Presupuesto o TTL de sesión x402 excedido                |
| `approval.requested`   | Transacción de alto valor en espera de aprobación humana |

## Payload del webhook

Cada entrega de webhook incluye un payload JSON con esta estructura:

```json theme={null}
{
  "id": "evt_abc123",
  "type": "payment.completed",
  "created_at": "2025-06-15T14:30:00Z",
  "data": {
    "transaction_id": "tx_xyz789",
    "agent_id": "agent_abc123",
    "amount": "50.00",
    "token": "USDC",
    "chain": "eip155:8453",
    "hash": "0xabc...def",
    "status": "confirmed"
  }
}
```

## Verificación de firmas

Cada entrega de webhook incluye un encabezado de firma para verificación. Siempre verifique las firmas antes de procesar eventos de webhook.

### Cómo funciona

AgentWallex firma cada payload de webhook usando el secreto que proporcionó al registrarse. La firma se envía en el encabezado `X-AgentWallex-Signature`.

### Ejemplo de verificación

<CodeGroup>
  ```typescript TypeScript theme={null}
  import crypto from "crypto";

  function verifyWebhookSignature(
    payload: string,
    signature: string,
    secret: string
  ): boolean {
    const expected = crypto
      .createHmac("sha256", secret)
      .update(payload)
      .digest("hex");
    return crypto.timingSafeEqual(
      Buffer.from(signature),
      Buffer.from(expected)
    );
  }

  // In your webhook handler
  app.post("/webhooks/agentwallex", (req, res) => {
    const signature = req.headers["x-agentwallex-signature"] as string;
    const isValid = verifyWebhookSignature(
      JSON.stringify(req.body),
      signature,
      "whsec_your_signing_secret"
    );

    if (!isValid) {
      return res.status(401).send("Invalid signature");
    }

    // Process the event
    const event = req.body;
    console.log(`Received ${event.type} event`);
    res.status(200).send("OK");
  });
  ```

  ```python Python theme={null}
  import hmac
  import hashlib

  def verify_webhook_signature(payload: bytes, signature: str, secret: str) -> bool:
      expected = hmac.new(
          secret.encode(),
          payload,
          hashlib.sha256
      ).hexdigest()
      return hmac.compare_digest(signature, expected)
  ```
</CodeGroup>

<Warning>
  Siempre use comparación en tiempo constante (por ejemplo, `timingSafeEqual` o `hmac.compare_digest`) al verificar firmas para prevenir ataques de temporización.
</Warning>

## Prueba de webhooks

Envíe un evento de prueba a su endpoint de webhook:

```bash theme={null}
curl -X POST https://api.agentwallex.com/api/v1/webhooks/whk_abc123/test \
  -H "X-API-Key: awx_your_api_key"
```

## Visualización de entregas

Consulte el historial de entregas de un webhook:

```bash theme={null}
curl -X GET https://api.agentwallex.com/api/v1/webhooks/whk_abc123/deliveries \
  -H "X-API-Key: awx_your_api_key"
```

## Gestión de webhooks

```bash theme={null}
# List all webhooks
GET /webhooks

# Get a specific webhook
GET /webhooks/:id

# Update a webhook
PUT /webhooks/:id

# Delete a webhook
DELETE /webhooks/:id
```

## Mejores prácticas

<Tip>
  Responda a las entregas de webhook con un código de estado 2xx dentro de 5 segundos. Si su manejador necesita realizar procesamiento pesado, confirme la recepción del webhook inmediatamente y procese de forma asíncrona.
</Tip>

* **Siempre verifique las firmas** antes de procesar eventos.
* **Maneje duplicados** — Las entregas de webhook pueden reintentarse. Use el campo `id` para idempotencia.
* **Devuelva 200 rápidamente** — Confirme la recepción antes de realizar procesamiento pesado.
* **Monitoree las fallas de entrega** — Consulte el endpoint de entregas para detectar entregas fallidas.
* **Use filtros de eventos específicos** — Suscríbase solo a los eventos que necesita en lugar de recibir todos los eventos.