Configurar un webhook

En esta guía crearás un webhook, lo limitarás a los eventos que necesitas y comprobarás que tu endpoint recibe peticiones firmadas. Puedes hacerlo todo en el panel o con la API de webhooks.

Antes de empezar

• Una URL pública que acepte peticiones POST. Se recomienda encarecidamente usar HTTPS. Las URL en localhost o en rangos de IP privadas se rechazan; para el desarrollo local, usa un túnel como ngrok o Cloudflare Tunnel.
• Un endpoint que conserve el cuerpo en bruto de la petición para poder verificar la firma.
• Para la API, una clave con Full Access.
• Margen para un webhook más. Pay as you go incluye 3 endpoints; Pro, 10, y Business y Custom, 100.

Crear el webhook

curl https://api.emailit.com/v2/webhooks \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production events",
    "url": "https://acme.com/webhooks/emailit",
    "events": ["email.delivered", "email.bounced", "email.complained"]
  }'

Elegir los eventos

Un webhook recibe todos los tipos de eventos o solo los tipos que selecciones.

curl -X POST https://api.emailit.com/v2/webhooks/wh_2xGk8Hd3RvN6qT1mWsB9cL4pZ7e \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"all_events": false, "events": ["email.received", "email.held", "email.canceled"]}'

Filtrar eventos por payload

Un filtro de payload entrega un evento solo cuando sus datos cumplen tus reglas. Los filtros se aplican además de la selección de eventos: un evento tiene que estar suscrito y cumplir el filtro.

Úsalo para repartir el tráfico entre endpoints, por ejemplo un webhook por línea de producto, o para descartar eventos que, de lo contrario, ignorarías en el código.

• Modo de coincidencia: All rules match (all) o Any rule matches (any).
• Reglas: hasta 25. Cada regla tiene un campo, un operador y un valor.
• Campo: una ruta con puntos dentro del data.object del evento, por ejemplo to, status, meta.plan o, en los eventos de clic, link.url. El prefijo payload. es opcional, así que payload.from y from son equivalentes.
• Las comparaciones distinguen entre mayúsculas y minúsculas y comparan los valores como texto, salvo greater_than y less_than, que comparan números.

curl -X POST https://api.emailit.com/v2/webhooks/wh_2xGk8Hd3RvN6qT1mWsB9cL4pZ7e \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "match": "all",
      "rules": [
        { "field": "to", "operator": "ends_with", "value": "@acme.com" },
        { "field": "meta.plan", "operator": "in", "value": ["pro", "business"] }
      ]
    }
  }'

Más ejemplos:

Si un espacio de trabajo pasa a Pay as you go, los filtros existentes se conservan, pero se ignoran, y se entregan todos los eventos suscritos.

Enviar un evento de prueba

Una prueba envía de inmediato un evento de ejemplo a tu URL, firmado con el secreto actual del webhook. Se ignoran los eventos suscritos y los filtros, la petición no se reintenta y no aparece en la pestaña Requests. Cada webhook permite 5 pruebas por minuto.

curl https://api.emailit.com/v2/webhooks/wh_2xGk8Hd3RvN6qT1mWsB9cL4pZ7e/test \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "email.delivered"}'

Los eventos de prueba usan datos de ejemplo, con un event_id que empieza por evt_test_, y su forma puede diferir ligeramente de la de los eventos reales. Desarrolla tu controlador a partir de la referencia de eventos y confírmalo con un envío real.

Activar o desactivar un webhook

Desactiva un webhook para detener las entregas sin perder su configuración, por ejemplo durante un mantenimiento.

• Panel: abre el menú de acciones y selecciona Disable webhook o Enable webhook. La página del webhook muestra el estado Enabled o Disabled.
• API: llama a Actualizar un webhook con {"enabled": false} o {"enabled": true}.

Mientras un webhook está desactivado, no se ponen en cola eventos nuevos para él y las peticiones que ya esperaban un reintento quedan en pausa. Los eventos que ocurren mientras está desactivado no se entregan más tarde; si los necesitas, léelos con la API de eventos. Emailit también desactiva los webhooks automáticamente tras 3 días de fallos; consulta Reintentos y fallos.

Al eliminar un webhook se descartan todos sus eventos pendientes.

Rotar el secreto

Rota el secreto si puede haberse filtrado, o como medida de seguridad habitual.

• Panel: abre el menú de acciones, selecciona Webhook secret y después Reset. El nuevo secreto se muestra una sola vez.
• API: llama a Rotar el secreto de firma. La respuesta contiene el nuevo secret. Obtener un webhook también devuelve el secreto actual.

El secreto anterior deja de funcionar de inmediato, y todas las peticiones a partir de ese momento, incluidos los reintentos de eventos anteriores, se firman con el nuevo. Para rotarlo sin rechazar peticiones, haz que tu endpoint acepte cualquiera de los dos secretos durante unos minutos, restablece el secreto, despliega el nuevo valor y después elimina el anterior.

Comprobar que funciona

1. Envía un evento de prueba y confirma que tu endpoint devuelve 2xx.
2. Envía un email real o dispara el evento al que te suscribiste.
3. En la pestaña Requests del webhook, la petición muestra Delivered. La hora de Last used del webhook se actualiza.

Ver también