Saltar al contenido principal

​
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

EventoDescripción
payment.completedTransacción confirmada on-chain
payment.failedTransacción fallida o revertida
payment.pendingTransacción enviada, esperando confirmación
agent.frozenBilletera del agente fue congelada
agent.unfrozenBilletera del agente fue descongelada
policy.violatedTransacción rechazada por el motor de políticas
x402.session.expiredPresupuesto o TTL de sesión x402 excedido
approval.requestedTransacció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");
});
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.