Descripción general
Notifuse gestiona dos tipos de webhooks:
-
Webhooks entrantes: llamadas de los proveedores de correo (Amazon SES, Mailgun, Postmark, etc.) que informan a Notifuse de rebotes, quejas, entregas y otros eventos de correo. Se configuran automáticamente al configurar una integración de correo.
-
Webhooks salientes: llamadas HTTP que Notifuse envía a tu servidor cuando ocurren eventos. De ellos trata esta página.
Un webhook saliente envía una petición HTTP POST a tu servidor cuando ocurre un evento concreto en Notifuse. Sirven para:
- Sincronizar los datos de los contactos con tu CRM u otros sistemas
- Lanzar flujos de trabajo en herramientas de automatización externas
- Crear integraciones y dashboards propios
- Reaccionar en tiempo real a la interacción con los correos
Crear una suscripción de webhook
Crea una suscripción de webhook en la consola, desde Configuración → Webhooks → Añadir punto final, donde eliges la URL y los tipos de evento:
O créala por la API:
curl -X POST "https://your-instance.com/api/webhookSubscriptions.create" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workspace_id": "your_workspace",
"name": "Production Webhook",
"url": "https://api.example.com/webhooks/notifuse",
"event_types": ["contact.created", "contact.updated", "email.sent"]
}'
Tipos de evento disponibles
Eventos de contacto
| Evento | Descripción |
|---|---|
contact.created | Se añadió un contacto nuevo al espacio de trabajo |
contact.updated | Se modificaron los datos de un contacto |
contact.deleted | Se eliminó un contacto de forma definitiva |
Eventos de lista
| Evento | Descripción |
|---|---|
list.subscribed | El contacto se suscribió a una lista |
list.unsubscribed | El contacto se dio de baja de una lista |
list.confirmed | El contacto confirmó una suscripción con doble confirmación |
list.resubscribed | Un contacto que se había dado de baja volvió a suscribirse |
list.bounced | Rebotó un correo enviado al contacto |
list.complained | El contacto marcó un correo como spam |
list.pending | La suscripción del contacto espera confirmación |
list.removed | Se quitó al contacto de la lista |
Eventos de segmento
| Evento | Descripción |
|---|---|
segment.joined | El contacto entró en un segmento (cumple sus criterios) |
segment.left | El contacto salió de un segmento (ya no cumple sus criterios) |
Eventos de correo
| Evento | Descripción |
|---|---|
email.sent | Se envió el correo al contacto |
email.delivered | El servidor del destinatario confirmó la entrega del correo |
email.opened | El contacto abrió el correo |
email.clicked | El contacto hizo clic en un enlace del correo |
email.bounced | La entrega del correo falló |
email.complained | El contacto marcó el correo como spam |
email.unsubscribed | El contacto se dio de baja desde el enlace del correo |
Eventos personalizados
| Evento | Descripción |
|---|---|
custom_event.created | Se registró un evento personalizado nuevo |
custom_event.updated | Se actualizó un evento personalizado |
custom_event.deleted | Se eliminó un evento personalizado (borrado lógico) |
Filtros de eventos personalizados
Para los eventos personalizados, puedes filtrar si quieres por goal_types y event_names:
{
"event_types": ["custom_event.created"],
"custom_event_filters": {
"goal_types": ["purchase", "subscription"],
"event_names": ["orders/fulfilled", "payment.succeeded"]
}
}
Filtrar por lista y por segmento
Por defecto, una suscripción a los eventos list.* recibe un evento de todas las listas del espacio de trabajo, y una suscripción a los eventos segment.*, de todos los segmentos. Puedes acotarla con list_ids y segment_ids:
{
"event_types": ["list.subscribed", "list.unsubscribed", "segment.joined"],
"list_ids": ["newsletter", "product_updates"],
"segment_ids": ["vip_customers"]
}
list_idssolo se aplica a los eventoslist.*, ysegment_ids, solo a los eventossegment.*. Ninguno de los dos afecta a los tipos de evento de contacto, de correo ni de eventos personalizados.- Omitir un filtro, o enviar un array vacío, equivale a “todas las listas” o “todos los segmentos”. Las suscripciones creadas antes de que existieran estos filtros siguen funcionando así.
- Puedes cambiar los dos filtros más adelante con
webhookSubscriptions.update.
Filtra siempre que puedas. Un espacio de trabajo con listas grandes genera una entrega por contacto en cada evento de lista, así que una suscripción que necesita una sola lista pero las recibe todas hace trabajar a tu instancia en eventos que luego descarta.
Campos de la suscripción
Además de su nombre, su URL y sus tipos de evento, una suscripción informa de:
| Campo | Descripción |
|---|---|
enabled | Si la suscripción está entregando ahora mismo |
source | Qué la creó. Ausente si la creaste tú; zapier si la creó la integración con Zapier |
consecutive_failures | Intentos de entrega que han fallado seguidos. Vuelve a cero con el primer éxito |
failing_since | Cuándo empezó la racha de fallos actual. Se borra con el primer éxito |
disabled_reason | Por qué se desactivó la suscripción automáticamente. Ausente si la desactivaste tú |
last_delivery_at | Cuándo fue la última entrega correcta |
Advertencia
Una suscripción con source la creó otra herramienta, que es su dueña. Si eliminas desde Notifuse una suscripción creada por Zapier, el Zap que depende de ella deja de funcionar sin avisar, y el Zap no la vuelve a crear por sí solo. Desactiva el Zap en Zapier en su lugar.
Cuándo desactiva Notifuse una suscripción
Notifuse retira un endpoint que deja de responder solo cuando se cumplen las dos condiciones: 20 fallos consecutivos y una racha de fallos de más de dos horas. Una caída breve (un despliegue, un reinicio, un receptor inaccesible un momento durante una importación) nunca desactiva tu suscripción, por muchas entregas que rechace mientras tanto. Esas entregas se reintentan con la espera progresiva habitual.
La excepción es un endpoint que responde 410 Gone: se retira de inmediato, porque ese código significa que el receptor afirma que la suscripción ya no existe.
Al volver a activar una suscripción se borra su historial de fallos, así que el siguiente fallo no la vuelve a retirar.
Adónde puede entregar Notifuse
Tu endpoint tiene que ser accesible desde internet. Notifuse se niega a conectarse a direcciones privadas, de loopback, link-local y reservadas, incluido el endpoint de metadatos de la instancia en la nube. Vuelve a comprobarlo en cada redirección, así que también rechaza una URL pública que redirige a una interna. Una suscripción cuya URL apunta a una de esas direcciones se rechaza al guardarla.
Nota
Solo en instalaciones autoalojadas: para entregar webhooks a propósito a un servicio de tu propia red privada (un contenedor en la misma red de Docker, una herramienta de automatización interna), define WEBHOOK_DELIVERY_ALLOW_PRIVATE_HOSTS=true. No la definas en ningún despliegue donde pueda crear suscripciones o editar automatizaciones alguien a quien no confiarías tu red interna. El mismo ajuste cubre los nodos webhook de las automatizaciones.
Una entrega rechazada por este motivo se reintenta como cualquier otro fallo, pero nunca cuenta para desactivar la suscripción, así que basta con corregir la URL o el ajuste para que se reanuden las entregas.
Estructura del payload
Todos los payloads de webhook siguen esta estructura:
{
"id": "delivery_abc123",
"type": "contact.created",
"timestamp": "2024-01-15T10:30:00Z",
"workspace_id": "ws_1234567890",
"data": {
// Event-specific data
}
}
| Campo | Descripción |
|---|---|
id | Identificador único de la entrega del webhook |
type | El tipo de evento que disparó el webhook |
timestamp | Marca de tiempo ISO 8601 del envío del webhook |
workspace_id | El espacio de trabajo donde ocurrió el evento |
data | Los datos propios del evento |
Ejemplo: contacto creado
{
"id": "delivery_abc123",
"type": "contact.created",
"timestamp": "2024-01-15T10:30:00Z",
"workspace_id": "ws_1234567890",
"data": {
"email": "user@example.com",
"id": "contact_12345",
"external_id": "ext_67890",
"first_name": "John",
"last_name": "Doe",
"tags": ["newsletter", "customer"],
"tracking_opens_consent": "granted",
"tracking_clicks_consent": null,
"tracking_consent_updated_at": "2024-01-15T10:30:00Z",
"tracking_consent_source": "api",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
}
Ejemplo: correo enviado
{
"id": "delivery_def456",
"type": "email.sent",
"timestamp": "2024-01-15T10:30:00Z",
"workspace_id": "ws_1234567890",
"data": {
"message_id": "msg_xyz789",
"email": "user@example.com",
"subject": "Welcome to our newsletter",
"broadcast_id": "bc_abc123",
"template_id": "welcome_email",
"created_at": "2024-01-15T10:30:00Z"
}
}
Ejemplo: correo abierto
{
"id": "delivery_ghi789",
"type": "email.opened",
"timestamp": "2024-01-15T11:45:00Z",
"workspace_id": "ws_1234567890",
"data": {
"message_id": "msg_xyz789",
"email": "user@example.com",
"subject": "Welcome to our newsletter",
"broadcast_id": "bc_abc123",
"template_id": "welcome_email",
"created_at": "2024-01-15T11:45:00Z"
}
}
Ejemplo: entrada en un segmento
{
"id": "delivery_jkl012",
"type": "segment.joined",
"timestamp": "2024-01-15T10:30:00Z",
"workspace_id": "ws_1234567890",
"data": {
"email": "user@example.com",
"contact_id": "contact_12345",
"segment_id": "seg_vip_customers",
"segment_name": "VIP Customers",
"created_at": "2024-01-15T10:30:00Z"
}
}
Verificar las firmas de los webhooks
Notifuse firma todos los payloads de webhook según la especificación Standard Webhooks, con HMAC-SHA256.
Cabeceras
Cada petición de webhook incluye estas cabeceras:
| Cabecera | Descripción |
|---|---|
webhook-id | Identificador único de la entrega del webhook |
webhook-timestamp | Marca de tiempo Unix del envío del webhook |
webhook-signature | Firma HMAC-SHA256 del payload |
Verificar la firma
- Extrae la marca de tiempo y la firma de las cabeceras
- Construye el payload firmado:
{webhook-id}.{webhook-timestamp}.{body} - Calcula el HMAC-SHA256 con tu secreto de webhook
- Compáralo con la firma recibida
Ejemplos de código
const crypto = require('crypto');
function verifyWebhook(payload, headers, secret) {
const msgId = headers['webhook-id'];
const msgTimestamp = headers['webhook-timestamp'];
const msgSignature = headers['webhook-signature'];
// Check timestamp is within 5 minutes
const now = Math.floor(Date.now() / 1000);
if (Math.abs(now - parseInt(msgTimestamp)) > 300) {
throw new Error('Timestamp too old');
}
// Construct signed payload
const signedPayload = `${msgId}.${msgTimestamp}.${payload}`;
// Compute signature
const secretBytes = Buffer.from(secret.replace('whsec_', ''), 'base64');
const expectedSignature = crypto
.createHmac('sha256', secretBytes)
.update(signedPayload)
.digest('base64');
// Extract v1 signature
const signatures = msgSignature.split(' ');
for (const sig of signatures) {
const [version, signature] = sig.split(',');
if (version === 'v1' && signature === expectedSignature) {
return true;
}
}
throw new Error('Invalid signature');
}import hmac
import hashlib
import base64
import time
def verify_webhook(payload: str, headers: dict, secret: str) -> bool:
msg_id = headers.get('webhook-id')
msg_timestamp = headers.get('webhook-timestamp')
msg_signature = headers.get('webhook-signature')
# Check timestamp is within 5 minutes
now = int(time.time())
if abs(now - int(msg_timestamp)) > 300:
raise ValueError('Timestamp too old')
# Construct signed payload
signed_payload = f"{msg_id}.{msg_timestamp}.{payload}"
# Compute signature
secret_bytes = base64.b64decode(secret.replace('whsec_', ''))
expected_signature = base64.b64encode(
hmac.new(secret_bytes, signed_payload.encode(), hashlib.sha256).digest()
).decode()
# Extract v1 signature
for sig in msg_signature.split(' '):
version, signature = sig.split(',')
if version == 'v1' and signature == expected_signature:
return True
raise ValueError('Invalid signature')package main
import (
"crypto/hmac"
"crypto/sha256"
"encoding/base64"
"errors"
"fmt"
"math"
"strconv"
"strings"
"time"
)
func VerifyWebhook(payload string, headers map[string]string, secret string) error {
msgID := headers["webhook-id"]
msgTimestamp := headers["webhook-timestamp"]
msgSignature := headers["webhook-signature"]
// Check timestamp is within 5 minutes
ts, _ := strconv.ParseInt(msgTimestamp, 10, 64)
now := time.Now().Unix()
if math.Abs(float64(now-ts)) > 300 {
return errors.New("timestamp too old")
}
// Construct signed payload
signedPayload := fmt.Sprintf("%s.%s.%s", msgID, msgTimestamp, payload)
// Compute signature
secretBytes, _ := base64.StdEncoding.DecodeString(strings.TrimPrefix(secret, "whsec_"))
h := hmac.New(sha256.New, secretBytes)
h.Write([]byte(signedPayload))
expectedSig := base64.StdEncoding.EncodeToString(h.Sum(nil))
// Extract v1 signature
for _, sig := range strings.Split(msgSignature, " ") {
parts := strings.SplitN(sig, ",", 2)
if len(parts) == 2 && parts[0] == "v1" && parts[1] == expectedSig {
return nil
}
}
return errors.New("invalid signature")
}<?php
function verifyWebhook(string $payload, array $headers, string $secret): bool {
$msgId = $headers['webhook-id'] ?? '';
$msgTimestamp = $headers['webhook-timestamp'] ?? '';
$msgSignature = $headers['webhook-signature'] ?? '';
// Check timestamp is within 5 minutes
$now = time();
if (abs($now - (int)$msgTimestamp) > 300) {
throw new Exception('Timestamp too old');
}
// Construct signed payload
$signedPayload = "{$msgId}.{$msgTimestamp}.{$payload}";
// Compute signature
$secretBytes = base64_decode(str_replace('whsec_', '', $secret));
$expectedSignature = base64_encode(
hash_hmac('sha256', $signedPayload, $secretBytes, true)
);
// Extract v1 signature
foreach (explode(' ', $msgSignature) as $sig) {
[$version, $signature] = explode(',', $sig, 2);
if ($version === 'v1' && $signature === $expectedSignature) {
return true;
}
}
throw new Exception('Invalid signature');
}Reintentos
Notifuse reintenta las entregas fallidas con una espera exponencial.
Calendario de reintentos
Una entrega tiene hasta 10 intentos, el último unas 10 horas después del primero:
| Intento | Espera desde el anterior |
|---|---|
| 1 | Inmediato |
| 2 | 30 segundos |
| 3 | 1 minuto |
| 4 | 2 minutos |
| 5 | 5 minutos |
| 6 | 15 minutos |
| 7 | 30 minutos |
| 8 | 1 hora |
| 9 | 2 horas |
| 10 | 6 horas |
Si el décimo intento también falla, la entrega se marca como fallida y no se vuelve a reintentar.
Criterio de éxito
Una entrega tiene éxito cuando tu endpoint devuelve un código de estado HTTP 2xx (200-299).
Condiciones de fallo
Un intento de entrega falla si:
- Tu endpoint devuelve un código de estado distinto de 2xx
- Tu endpoint tarda más de 10 segundos en responder
- No se puede llegar al endpoint (error de DNS, conexión rechazada, etc.)
Desactivación automática
Un endpoint que se ha movido, se ha retirado del servicio o ha perdido su registro DNS no vuelve por sí solo, y Notifuse no acumula entregas para él indefinidamente.
Tras una larga racha de fallos seguidos, Notifuse desactiva la suscripción y guarda el motivo en ella, para que puedas distinguirla de una que desactivaste tú. El contador es por suscripción y una sola entrega correcta lo pone a cero, así que solo se desactiva un endpoint que falla de forma persistente.
Dos respuestas reciben un trato especial:
429 Too Many Requestsnunca cuenta como fallo. Significa que tu servidor pide menos peticiones, y un espacio de trabajo con tanta actividad como para que lo limiten no debería perder su integración por eso. La entrega se reintenta según el calendario normal.410 Gonees definitivo desde la primera respuesta. Es la forma estándar de que un receptor diga “esta suscripción ya no existe, deja de enviar”, así que la suscripción se retira de inmediato, sin la racha de fallos habitual. Una suscripción que creaste tú se desactiva y se guarda ese motivo; una creada por otra herramienta, como Zapier, se elimina directamente, porque la herramienta la vuelve a crear cuando la necesita. Con404no pasa lo mismo: un endpoint que falta durante un rato se reintenta como cualquier otro fallo.
Para recuperar una suscripción desactivada, corrige el endpoint y vuelve a activarla.
Nota
Una suscripción desactivada descarta los eventos en lugar de guardarlos en cola. Las entregas que tocaban mientras estaba desactivada, la desactivaras tú o Notifuse, se marcan como fallidas en el registro de entregas y no se reenvían cuando la vuelves a activar. Para recuperar los eventos de una caída, léelos desde la API.
Eliminar una suscripción
Al eliminar una suscripción también se descartan las entregas que tenía en cola, así que no queda nada por reintentar ni ninguna cola que vaciar antes.
Si piensas recuperar el endpoint, desactiva la suscripción en lugar de eliminarla: la desactivación se puede deshacer y conserva la suscripción con su secreto de firma y su historial de entregas. Una suscripción eliminada no se puede restaurar, y al volver a crearla se genera un secreto de firma nuevo.
Buenas prácticas
Devuelve un 2xx enseguida
Devuelve una respuesta correcta lo antes posible y, si hace falta, procesa el payload de forma asíncrona:
// Good: Acknowledge quickly, process later
app.post('/webhooks/notifuse', async (req, res) => {
// Quickly validate signature
verifyWebhook(req.body, req.headers, SECRET);
// Queue for async processing
await queue.add('process-webhook', req.body);
// Respond immediately
res.status(200).json({ received: true });
});
Gestiona las entregas duplicadas
En casos raros, un webhook se entrega más de una vez. Usa la cabecera webhook-id para que el procesamiento sea idempotente:
app.post('/webhooks/notifuse', async (req, res) => {
const webhookId = req.headers['webhook-id'];
// Check if we've already processed this webhook
if (await hasProcessed(webhookId)) {
return res.status(200).json({ received: true, duplicate: true });
}
// Mark as processed before handling
await markProcessed(webhookId);
// Process the webhook
await processWebhook(req.body);
res.status(200).json({ received: true });
});
Verifica las firmas
Verifica siempre las firmas de los webhooks en producción, para asegurarte de que las peticiones vienen de Notifuse.
Vigila los fallos de entrega
En la consola, Configuración → Webhooks muestra la tasa de éxito de cada suscripción en los últimos 7 días y su última entrega correcta. Abre una suscripción para ver sus entregas correctas y fallidas de las últimas 24 horas o de los últimos 7 días, y elige Ver entregas para listarlas en los registros.
Por la API, añade status (pending, delivering, delivered o failed) para listar solo las entregas en ese estado; cualquier otro valor devuelve un 400. failed también incluye las entregas que esperan un reintento, que vuelven a delivering al reenviarse, así que una entrega que aparece como fallida todavía puede tener éxito:
curl "https://your-instance.com/api/webhookSubscriptions.deliveries?workspace_id=ws_123&subscription_id=whsub_456&status=failed" \
-H "Authorization: Bearer YOUR_API_KEY"
Probar los webhooks
Enviar un webhook de prueba
Usa el endpoint de prueba para comprobar la configuración de tu webhook:
curl -X POST "https://your-instance.com/api/webhookSubscriptions.test" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workspace_id": "your_workspace",
"id": "whsub_a1b2c3d4e5f6",
"event_type": "contact.created"
}'
Con el parámetro opcional event_type, la prueba envía un payload de ejemplo realista para ese tipo de evento. Sin él, la prueba envía un payload genérico.
Desarrollo local
En desarrollo local, usa herramientas como ngrok o localtunnel para exponer tu servidor local:
# Start ngrok
ngrok http 3000
# Use the ngrok URL as your webhook endpoint
# https://abc123.ngrok.io/webhooks/notifuse
Permisos
Las suscripciones salientes dependen del permiso Suscripciones de webhook. Con leído, un miembro lista las suscripciones, abre una y ve su historial de entregas, incluido el payload de cada evento y el código de estado y el cuerpo de la respuesta del endpoint. Con escribir, crea, actualiza, elimina, activa y desactiva suscripciones, y lanza una entrega de prueba, que cuenta como escritura porque hace que tu servidor haga una llamada saliente.
Las llamadas entrantes de los proveedores dependen del permiso Eventos de webhook. Con leído, un miembro ve las llamadas sin procesar que tus proveedores de correo han enviado a Notifuse, con las direcciones de los destinatarios y los diagnósticos del proveedor. Escribir en Eventos de webhook no controla nada por ahora: las filas llegan por las rutas de llamada de los proveedores, que no llevan sesión ni comprueban permisos, así que concederlo no da nada. La consola lo muestra concedido y bloqueado.
El catálogo de tipos de evento disponibles no necesita permiso: cualquier miembro o clave autenticados pueden listarlo.
Dos acciones quedan reservadas al propietario del espacio de trabajo, tenga los permisos que tenga un miembro o una clave API:
- Regenerar el secreto de firma de una suscripción. El secreto también está oculto para todos salvo el propietario, así que leer Suscripciones de webhook nunca lo expone: un miembro puede listar suscripciones e inspeccionar entregas sin ver nunca la clave que firma esos payloads.
- Registrar webhooks en un proveedor de correo, porque usa las credenciales del proveedor guardadas en tu integración.
Advertencia
Escribir en Suscripciones de webhook llega más lejos de lo que sugiere su nombre. Una suscripción elige los eventos que recibe, así que quien tenga este permiso puede suscribirse a los eventos de contacto y de correo y recibir esos datos en la URL que quiera. Concédelo como concederías el acceso de lectura a los contactos y al historial de mensajes que hay detrás de esos eventos.
Notas
- En producción, los webhooks requieren endpoints HTTPS
- El secreto de firma se genera automáticamente al crear una suscripción
- Usa
webhookSubscriptions.regenerateSecretpara rotar el secreto de firma - Consulta la referencia de la API para la documentación completa de los endpoints
