Webhooks

Reciba eventos de correo electrónico en tiempo real.

Descripción general

Al configurar webhooks, cuando ocurren eventos como envío, apertura o clic de correos, se envía una solicitud HTTP POST a la URL especificada.

Los webhooks se pueden configurar en Panel > Webhooks.

Tipos de eventos

Event	Description
`email.sent`	Cuando se envía un correo electrónico
`email.delivered`	Cuando el correo es entregado al destinatario
`email.opened`	Cuando el destinatario abre el correo
`email.clicked`	Cuando el destinatario hace clic en un enlace del correo
`email.bounced`	Cuando un correo es rebotado
`email.complained`	Cuando el destinatario reporta como spam
`subscriber.created`	Cuando se agrega un nuevo suscriptor
`subscriber.unsubscribed`	Cuando un suscriptor cancela su suscripción
`campaign.sent`	Cuando se inicia el envío de una campaña
`campaign.completed`	Cuando se completa el envío de una campaña

Formato del payload

Todas las solicitudes de webhook incluyen un payload JSON con el siguiente formato:

{
  "event": "email.opened",
  "timestamp": "2026-01-10T12:00:00+00:00",
  "data": {
    "campaign_id": 123,
    "campaign_uuid": "abc-123...",
    "campaign_name": "January Newsletter",
    "subscriber_id": 456,
    "subscriber_uuid": "def-456...",
    "subscriber_email": "user@example.com",
    "ip_address": "1.2.3.4",
    "user_agent": "Mozilla/5.0...",
    "occurred_at": "2026-01-10T12:00:00+00:00"
  }
}

Encabezados de solicitud

Header	Description
`Content-Type`	`application/json`
`X-Webhook-ID`	UUID del webhook
`X-Webhook-Event`	Tipo de evento (ej: email.opened)
`X-Webhook-Signature`	Firma HMAC-SHA256

Verificación de firma

Verifique el encabezado X-Webhook-Signature para confirmar la autenticidad de la solicitud del webhook. La firma es un hash HMAC-SHA256 usando el secreto del webhook y el cuerpo de la solicitud.

Ejemplo PHP

<?php
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'];
$secret = 'your_webhook_secret';

$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    die('Invalid signature');
}

$data = json_decode($payload, true);
// Process the event...

Ejemplo Node.js

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

// Express.js example
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const payload = JSON.stringify(req.body);

  if (!verifySignature(payload, signature, 'your_secret')) {
    return res.status(401).send('Invalid signature');
  }

  // Process the event...
  res.status(200).send('OK');
});

Política de reintentos

• Si el envío del webhook falla (respuesta distinta de 2xx), no se reintenta automáticamente.
• Después de 5 fallos consecutivos, el webhook se desactiva automáticamente.
• Los webhooks desactivados pueden reactivarse desde el panel de control.
• El tiempo de respuesta debe ser inferior a 10 segundos.

Mejores prácticas

• Siempre verifique la firma para confirmar la autenticidad de la solicitud.
• Procese los webhooks lo más rápido posible (dentro de 5 segundos).
• Encole las tareas largas y devuelva 200 OK inmediatamente.
• Use endpoints HTTPS para transmitir datos de forma segura.