Webhook de eventos

Qué es

En vez de hacer polling de /v1/events, puedes registrar una URL y Axelo te enviará un POST por cada evento de entrega — de email, WhatsApp y wallet: sent · delivered · opened · clicked · bounced · complained · failed · suppressed También eventos de cuenta de tus dominios propios: domain.verified y domain.verification_failed (channel domain, sin job_id; el result trae {domain, transport, status}). Los recibes cuando un dominio pasa de pendiente a verificado (o falla), sin tener que consultar. Para email: sent = aceptado por el servidor de Axelo; delivered = el servidor del destinatario confirmó la recepción (250). opened/clicked prueban además que el destinatario interactuó. La entrega es asíncrona y con reintentos automáticos (backoff exponencial) si tu endpoint no responde 2xx.

Configurar

Desde el dashboard (admin → detalle del tenant → Webhook de eventos) registra tu URL. Al guardarla se genera un secreto de firma (whsec_...) que se muestra ahí mismo. Deja la URL vacía para deshabilitar.

Payload

{
  "id": 2869,
  "tenant_id": "tu-tenant",
  "channel": "email",
  "event_type": "sent",
  "job_id": "0e35a2ba-afe5-4ae1-a82c-0b717fd09b48",
  "recipient": "cliente@ejemplo.com",
  "result": { "delivered_to": "cliente@ejemplo.com", "sending_domain": "mail.axelo.mx" },
  "timestamp": "2026-08-05T03:22:53Z"
}

Headers de cada request:

Header	Valor
`Content-Type`	`application/json`
`X-Axelo-Event`	el `event_type` (para enrutar rápido)
`X-Axelo-Signature-256`	`sha256=<hmac>` — firma del cuerpo

id es el event_id único. La entrega es at-least-once (en un reinicio un evento podría repetirse): usa id para deduplicar.

En eventos bounced de envíos por Resend, result incluye el detalle del rebote: bounce_type (Permanent | Transient), bounce_subtype y diagnostic_code (p. ej. "smtp; 550 5.4.4 Invalid domain"). Solo los rebotes Permanent suprimen al destinatario.

Verificar la firma

Calcula HMAC-SHA256 sobre el cuerpo crudo con tu events_webhook_secret y compáralo (en tiempo constante) con el header X-Axelo-Signature-256.

import crypto from 'crypto'

function verify(rawBody, signatureHeader, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex')
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader))
}

// Express: usa el cuerpo CRUDO (no el parseado)
app.post('/webhooks/axelo', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verify(req.body, req.get('X-Axelo-Signature-256'), process.env.AXELO_WEBHOOK_SECRET)) {
    return res.status(401).end()
  }
  const event = JSON.parse(req.body)
  // ... procesar event ...
  res.status(200).end()
})

$raw = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $raw, getenv('AXELO_WEBHOOK_SECRET'));
if (!hash_equals($expected, $_SERVER['HTTP_X_AXELO_SIGNATURE_256'] ?? '')) {
    http_response_code(401);
    exit;
}
$event = json_decode($raw, true);
// ... procesar $event ...
http_response_code(200);

Firma el cuerpo crudo tal cual llega, antes de parsear el JSON — reserializar cambia los bytes e invalida la firma.

Reintentos

Si tu endpoint devuelve un código fuera de 2xx (o falla la conexión), Axelo reintenta con backoff. Responde 2xx en cuanto recibas el evento (procesa de forma asíncrona de tu lado) para evitar reintentos innecesarios.

Introducción

Envíos

Jobs

Eventos

Dominios

Webhooks

Webhook de eventos

Qué es

Configurar

Payload

Verificar la firma

Reintentos

​Qué es

​Configurar

​Payload

​Verificar la firma

​Reintentos

Qué es

Configurar

Payload

Verificar la firma

Reintentos