Pasos webhook | AgentsMail.io Documentation

Un paso webhook llama a una URL tuya cuando un recorrido llega a él. Es la forma en que una secuencia avisa a tus propios sistemas de que algo ha pasado: crear una tarea, actualizar un registro del CRM, iniciar tu propio flujo de trabajo. AgentsMail solo envía a esa URL. No se lee nada de tu respuesta: solo se guarda el código de estado HTTP.

Las dos formas

Cuál recibes depende del tipo de secuencia al que pertenece el paso, y el campo event te lo dice sin tener que adivinar.

Secuencia	`event`	Lleva
Un recorrido en el que hay personas inscritas	`sequence.node.webhook`	Un contacto, cuando pasa por el paso
Una serie en fecha fija	`sequence.series.webhook`	Un lote de contactos: la audiencia de ese paso

Una serie actúa sobre toda una audiencia a la vez. Enviar una solicitud por contacto significaría veinte mil solicitudes a tu puerta para una lista de veinte mil contactos, así que la audiencia se divide en lotes y cada lote es una solicitud. Ambas formas son permanentes: la de lotes no sustituye a la de un solo contacto.

Un contacto

json

{
  "event": "sequence.node.webhook",
  "occurredAt": "2026-09-21T09:00:00.000Z",
  "sequence": {"id": "…", "name": "Onboarding"},
  "node": {"id": "…"},
  "contact": {
    "id": "…",
    "email": "alice@example.com",
    "firstName": "Alice",
    "lastName": null
  }
}

Un lote

json

{
  "event": "sequence.series.webhook",
  "occurredAt": "2026-09-21T09:00:00.000Z",
  "sequence": {"id": "…", "name": "Spring launch"},
  "node": {"id": "…"},
  "batch": {"index": 3, "size": 500},
  "contacts": [
    {
      "id": "…",
      "email": "alice@example.com",
      "firstName": "Alice",
      "lastName": null
    }
  ]
}

batch.index es la posición de ese lote dentro de una ejecución del paso, contando desde cero, y batch.size es cuántos contactos lleva. El par es estable: si alguna vez ves el mismo node.id + batch.index dos veces para la misma ejecución, son los mismos contactos, y eso es lo que te permite reconocer un lote que ya procesaste. La audiencia se congela cuando empieza el paso. Los contactos que llegan mientras salen los lotes pertenecen al paso siguiente, no a este.

Lo que nunca contiene

Tres cosas, y ninguna por casualidad:

ningún secreto: ninguna clave de API, y ningún enlace ni token de baja, que es una capacidad y no un identificador;
ningún id de organización;
no se lee ninguna respuesta tuya: el cuerpo que devuelves se descarta sin abrirlo.

Si necesitas saber a cuál de tus cuentas pertenece una llamada, ponlo en la propia URL: una ruta o una query string distinta por secuencia funciona, y nunca viaja en el payload.

Qué exigimos a tu URL

Solo https. Una URL http simple se rechaza al publicar.
Una dirección accesible públicamente. Las direcciones privadas, locales e internas se rechazan, incluido un nombre de host perfectamente público que resuelva a una de ellas, e incluida una dirección alcanzada a través de una redirección. Cada salto se vuelve a comprobar.
Como máximo tres redirecciones.
Una respuesta en cinco segundos. Pasado ese tiempo, la llamada es un tiempo agotado. Responde primero, trabaja después: confirma la recepción de la solicitud y haz el procesamiento aparte. Un lote está dimensionado para caber en esa ventana, así que mantén tu handler rápido antes que exhaustivo.

Cualquier 2xx es un éxito. Todo lo demás es un error, y no se adivina nada al respecto.

Cuando falla

Una llamada fallida nunca se reintenta. Una llamada webhook sale como máximo una vez: reintentar podría crear el mismo pedido, la misma tarea o el mismo registro dos veces de tu lado. Una llamada que falla es, para ti, una llamada que nunca ocurrió.

Un fallo no detiene el recorrido: el contacto sigue adelante, y el resto de la serie sale. El resultado de cada llamada se guarda, y la pantalla de la secuencia lo muestra en el propio paso:

Se muestra	Significado
correcta	Tu endpoint respondió un `2xx`.
error	Tu endpoint respondió otra cosa: se muestra el código de estado.
tiempo agotado	No volvió nada en cinco segundos.
destino rechazado	Nuestras reglas rechazaron la dirección antes de enviar nada.

En una serie, el paso muestra cuántos lotes salieron y cuántos fallaron, con el motivo del último fallo, por ejemplo 38 lotes · 2 fallidos (tiempo agotado). Como nada se reintenta, esa línea es el único lugar donde aparece un fallo parcial: un paso que parece correcto a simple vista puede haber perdido dos lotes.

Qué implica en otras partes

Los pasos webhook forman parte del grafo de la secuencia, y un paso cuya URL incumple nuestras reglas hace que la secuencia se niegue a publicarse: el mensaje nombra el paso.