Webhooks
Los webhooks envían eventos a tu backend en el momento en que ocurren: se entregó un mensaje, se hizo clic en un enlace, un contacto se dio de baja. Cada carga útil va firmada para que puedas confiar en ella, y las entregas fallidas se reintentan con backoff para que un corte breve nunca pierda un evento.
Lo que necesitarás
- Un endpoint HTTPS público para recibir los POST
- Una API key o acceso de administrador para registrar el webhook
Registra un endpoint
- 1
Abre Configuración → Webhooks
O llama a POST /v1/workspaces/{workspace_id}/webhooks. Proporciona tu URL HTTPS y elige los eventos que quieres.
- 2
Guarda el secreto de firma
Cada webhook tiene un secreto, mostrado al crearlo. Lo usarás para verificar cada petición entrante.
- 3
Añade cabeceras personalizadas (opcional)
Adjunta cabeceras (p. ej. un token de autenticación) que Climails enviará con cada entrega a tu endpoint.
Eventos a los que puedes suscribirte
- Email: email.delivered, email.bounce, email.complaint, email.unsubscribe, email.opened, email.clicked.
- SMS: sms.delivered, sms.failed.
- Contactos: contact.subscribed, contact.unsubscribed, contact.changed.
- Campañas: campaign.finished.
Verifica la firma
Cada petición lleva X-Senderbox-Timestamp y X-Senderbox-Sig. Recalcula el HMAC y compara: rechaza todo lo que no coincida y rechaza las marcas de tiempo antiguas para frenar las repeticiones.
// signature = HMAC_SHA256(secret, timestamp + "." + rawBody)
import crypto from "node:crypto";
function verify(rawBody, headers, secret) {
const ts = headers["x-senderbox-timestamp"];
const sig = headers["x-senderbox-sig"]; // "sha256=<hex>"
const expected = "sha256=" + crypto
.createHmac("sha256", secret)
.update(ts + "." + rawBody)
.digest("hex");
return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}Reintentos y fallos
Devuelve un 2xx rápidamente para confirmar la recepción. Si tu endpoint da error o agota el tiempo de espera, Climails reintenta con un backoff creciente: 30s, 2m, 10m, 1h, 6h, 24h.
- Tras 6 intentos fallidos la entrega se descarta.
- Un 4xx (salvo 408 y 429) se trata como terminal y no se reintenta: arregla el endpoint y se reanudará en el siguiente evento.
- Los endpoints están protegidos contra SSRF: se rechazan las direcciones internas/privadas.
Preguntas frecuentes
¿Cómo verifico que un webhook proviene realmente de Climails?
Recalcula HMAC-SHA256 sobre timestamp + "." + cuerpo en bruto con el secreto del webhook y compáralo con X-Senderbox-Sig. Usa una comparación de tiempo constante.
¿Qué pasa si mi servidor está caído?
Las entregas se reintentan con backoff (30s → 24h) a lo largo de hasta 6 intentos, así que un corte breve no perderá eventos.
¿Por qué mi webhook dejó de reintentar de inmediato?
Una respuesta 4xx (distinta de 408/429) se trata como un error permanente. Arregla el manejador; los nuevos eventos reanudan la entrega.
Empieza a enviar en minutos
Crea una cuenta gratuita, conecta tu dominio y llega a tu audiencia en todos los canales, sin tarjeta de crédito.
Plan gratuito para siempre · Sin tarjeta de crédito · Listo en minutos