Webhooks

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

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

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:

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

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");
});

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)

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

Prueba de webhooks

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

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:

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

# 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

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.

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.

Primeros Pasos

Plataforma

Características Principales

Guías

Descripción general

Configuración de webhooks

Mediante SDK

Mediante API

Tipos de eventos

Payload del webhook

Verificación de firmas

Cómo funciona

Ejemplo de verificación

Prueba de webhooks

Visualización de entregas

Gestión de webhooks

Mejores prácticas

​Descripción general

​Configuración de webhooks

​Mediante SDK

​Mediante API

​Tipos de eventos

​Payload del webhook

​Verificación de firmas

​Cómo funciona

​Ejemplo de verificación

​Prueba de webhooks

​Visualización de entregas

​Gestión de webhooks

​Mejores prácticas

Descripción general

Configuración de webhooks

Mediante SDK

Mediante API

Tipos de eventos

Payload del webhook

Verificación de firmas

Cómo funciona

Ejemplo de verificación

Prueba de webhooks

Visualización de entregas

Gestión de webhooks

Mejores prácticas