Saltar al contenido

Funciones

Webhooks

Recibe llamadas HTTP en tiempo real cuando ocurren eventos en tu espacio de trabajo.

Descripción general

Notifuse gestiona dos tipos de webhooks:

  1. 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.

  2. 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
Configuración, Webhooks: dos endpoints con sus eventos y su tasa de entregas correctas

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:

Los tipos de evento de un endpoint de webhook, elegidos con casillas, con Seleccionar todo

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

EventoDescripción
contact.createdSe añadió un contacto nuevo al espacio de trabajo
contact.updatedSe modificaron los datos de un contacto
contact.deletedSe eliminó un contacto de forma definitiva

Eventos de lista

EventoDescripción
list.subscribedEl contacto se suscribió a una lista
list.unsubscribedEl contacto se dio de baja de una lista
list.confirmedEl contacto confirmó una suscripción con doble confirmación
list.resubscribedUn contacto que se había dado de baja volvió a suscribirse
list.bouncedRebotó un correo enviado al contacto
list.complainedEl contacto marcó un correo como spam
list.pendingLa suscripción del contacto espera confirmación
list.removedSe quitó al contacto de la lista

Eventos de segmento

EventoDescripción
segment.joinedEl contacto entró en un segmento (cumple sus criterios)
segment.leftEl contacto salió de un segmento (ya no cumple sus criterios)

Eventos de correo

EventoDescripción
email.sentSe envió el correo al contacto
email.deliveredEl servidor del destinatario confirmó la entrega del correo
email.openedEl contacto abrió el correo
email.clickedEl contacto hizo clic en un enlace del correo
email.bouncedLa entrega del correo falló
email.complainedEl contacto marcó el correo como spam
email.unsubscribedEl contacto se dio de baja desde el enlace del correo

Eventos personalizados

EventoDescripción
custom_event.createdSe registró un evento personalizado nuevo
custom_event.updatedSe actualizó un evento personalizado
custom_event.deletedSe 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_ids solo se aplica a los eventos list.*, y segment_ids, solo a los eventos segment.*. 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:

CampoDescripción
enabledSi la suscripción está entregando ahora mismo
sourceQué la creó. Ausente si la creaste tú; zapier si la creó la integración con Zapier
consecutive_failuresIntentos de entrega que han fallado seguidos. Vuelve a cero con el primer éxito
failing_sinceCuándo empezó la racha de fallos actual. Se borra con el primer éxito
disabled_reasonPor qué se desactivó la suscripción automáticamente. Ausente si la desactivaste tú
last_delivery_atCuá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
  }
}
CampoDescripción
idIdentificador único de la entrega del webhook
typeEl tipo de evento que disparó el webhook
timestampMarca de tiempo ISO 8601 del envío del webhook
workspace_idEl espacio de trabajo donde ocurrió el evento
dataLos 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:

CabeceraDescripción
webhook-idIdentificador único de la entrega del webhook
webhook-timestampMarca de tiempo Unix del envío del webhook
webhook-signatureFirma HMAC-SHA256 del payload

Verificar la firma

  1. Extrae la marca de tiempo y la firma de las cabeceras
  2. Construye el payload firmado: {webhook-id}.{webhook-timestamp}.{body}
  3. Calcula el HMAC-SHA256 con tu secreto de webhook
  4. 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:

IntentoEspera desde el anterior
1Inmediato
230 segundos
31 minuto
42 minutos
55 minutos
615 minutos
730 minutos
81 hora
92 horas
106 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 Requests nunca 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 Gone es 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. Con 404 no 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.regenerateSecret para rotar el secreto de firma
  • Consulta la referencia de la API para la documentación completa de los endpoints