Webhooks y eventos
Los webhooks de cuenta envían lo que pasa en toda tu cuenta a una URL que tú eliges, en el momento: un lead nuevo, una reunión reservada, una oportunidad que cambia de etapa. Son lo que usan por debajo las integraciones con Zapier y n8n, y también puedes dirigirlos a tu propio endpoint. Si solo usas Zapier, no necesitas añadir un webhook tú mismo: la tarjeta Zapier de la página Desarrolladores empieza un Zap a partir de una plantilla, y el Zap crea su propio webhook.
Conviven con el webhook de proyecto de la página Respuestas de un correo, que sigue funcionando igual. Un webhook de proyecto cubre las interacciones de un solo correo. Un webhook de cuenta cubre todos los correos, más los eventos de abajo, y se firma del mismo modo.
Añadir un webhook
- Ve a Desarrolladores en el panel y busca la tarjeta Webhooks.
- Escribe la URL del endpoint (una URL
https://pública) y marca los Eventos que quieras. - Haz clic en Añadir webhook y copia el secreto de firma. Solo se muestra esta vez.
Cada webhook muestra cómo se creó (Panel, API, Zapier o n8n), su estado y su última entrega. Enviar prueba envía un ejemplo del evento elegido, con "test": true en su data. Eliminar quita el webhook. Una cuenta puede tener hasta 50.
Solo el propietario de la cuenta puede añadir o eliminar webhooks, y puede que antes se le pida volver a iniciar sesión.
Eventos
| Evento | Se dispara cuando |
|---|---|
interaction.received | Un destinatario interactúa con un correo: un voto, una valoración, una respuesta de quiz, un clic con seguimiento, una compra, etc. Las repeticiones deduplicadas no lo disparan. |
form.submitted | Se envía un formulario dentro de un correo (source: "email-form") o un formulario de registro (source: "signup-form"). |
contact.created | Se añade un contacto a una lista. |
contact.updated | Cambian los campos de un contacto. Guardar datos idénticos no lo dispara. |
lead.hot | La puntuación de interacción de un contacto cruza hacia arriba tu umbral de lead caliente. |
lead.new | Llega un lead nuevo por un formulario de registro o un formulario dentro de un correo. |
booking.created | Se reserva una reunión. |
booking.cancelled | Se cancela una reserva, con cancelledBy. Reprogramar no dispara ninguno de los dos eventos de reserva. |
deal.created | Se crea una oportunidad, venga de donde venga: el tablero, una regla automática, un recorrido, una propuesta o la API. |
deal.stage_changed | Una oportunidad cambia de etapa, incluidas ganada y perdida. |
purchase.completed | Un destinatario paga con un checkout dentro del correo. |
journey.completed | Un contacto llega al final de un recorrido. Si sale antes, no cuenta. |
experiment.decided | Alguien registra la decisión de un experimento: una ganadora, sin diferencia o no concluyente. |
experiment.completed | Llegan los resultados finales de un experimento: se ejecutó el análisis que cubre toda su ventana de observación. |
response.completed | Un destinatario respondió todos los bloques que cuenta un correo, por ejemplo cada pregunta de una encuesta. Una vez por destinatario y correo. |
review.submitted | Un destinatario envió una reseña desde un bloque de solicitud de reseña. Se activa una vez por reseña. |
Los eventos de contacto se disparan con importaciones, formularios de registro, la API, sincronizaciones y conectores de IA. Una sola escritura de más de 500 contactos (una importación CSV grande, por ejemplo) no dispara ninguno, para que una importación no lance miles de flujos. Un contacto añadido en la cuadrícula de contactos, escrito a mano o combinado desde un CSV, dispara contact.created. Las ediciones de contactos existentes en ella no disparan contact.updated, y tampoco lo hacen los pasos de recorrido Actualizar campo ni las respuestas guardadas.
lead.hot y lead.new se disparan sin importar los interruptores y límites de tus alertas de leads: suscribirse equivale a aceptarlos.
Los dos eventos de experimento llevan {experiment}, la misma forma que devuelve la API de experimentos: sus variantes, el último result del análisis, la decision registrada con la evidence que le dio el análisis, y una resultsUrl. experiment.completed se dispara una sola vez por experimento, aunque la decisión se haya registrado antes con una prueba secuencial. En un experimento dentro de un recorrido, la ganadora es una ruta: decision.pathIndex.
response.completed lleva el correo (projectId, projectName), la clave recipient y su contact, el sendId y el variant cuando lo envió un envío (si no, null), los blockIds contados y, en answers, la respuesta de cada bloque, el mismo valor que interaction.received lleva en event.value, con firstAnsweredAt y completedAt. Un correo cuenta cada encuesta, valoración, cuestionario, RSVP y formulario que ve el destinatario, salvo que el panel Respuestas del Estudio elija menos, y con menos de dos nunca se dispara. Cambiar una respuesta después no lo vuelve a disparar, y una vista sin destinatario (una vista previa, un enlace genérico) nunca se completa.
review.submitted lleva el correo (projectId, projectName), el blockId, lo reseñado en subject (kind, id, title), la rating, el title y el body, el displayName elegido, verifiedPurchase, el contact y el recipient, y submittedAt.
Payload
Cada entrega es un POST JSON con el mismo sobre:
{
"id": "evt_8c1f…",
"type": "deal.stage_changed",
"createdAt": 1790000000000,
"data": {
"deal": {
"id": "deal_abc123",
"title": "Annual plan",
"value": 1200,
"currency": "USD",
"pipelineId": "owner_default",
"stageId": "proposal-sent",
"stage": "Proposal sent",
"status": "open",
"source": "manual",
"listId": "list_abc123",
"rowId": "3f6c1b0e2d…",
"email": "[email protected]"
},
"fromStageId": "meeting-booked"
}
}
id es el mismo en cada entrega de un mismo evento y también se envía en la cabecera X-MailInApp-Idempotency-Key, así que puedes descartar sin riesgo una nueva entrega que ya procesaste. createdAt está en milisegundos epoch.
Para ver el data de cada tipo de evento, llama a GET /api/v1/events/sample o usa Enviar prueba.
Verificar la firma
Las entregas llevan las cabeceras X-MailInApp-Timestamp y X-MailInApp-Signature, calculadas exactamente igual que en un webhook de proyecto. Compruébalas sobre el cuerpo en bruto con tu secreto de firma y rechaza las marcas de tiempo de hace más de unos minutos. La documentación del webhook de proyecto incluye una función de Node.js lista para usar.
Reintentos
Tu endpoint tiene 5 segundos para responder con un 2xx. Cualquier otra cosa (tiempo agotado, estado de error, redirección) es un fallo, y la entrega se reintenta automáticamente, con intervalos crecientes durante varias horas, con el mismo cuerpo y la misma clave de idempotencia, a la URL actual del webhook. Responde rápido y haz el trabajo lento después.
- Si tu endpoint responde
410 Gone, el webhook se desactiva. Así es como se dan de baja los clientes REST Hooks. - Revocar una clave de API desactiva los webhooks creados con ella.
- Eliminar un webhook detiene sus reintentos pendientes.
Suscribirse por la API
Zapier, n8n y tu propio código pueden gestionar webhooks con una clave de API (Authorization: Bearer mia_live_…):
curl https://mailinapp.com/api/v1/webhooks \
-H "Authorization: Bearer mia_live_..." \
-H "Content-Type: application/json" \
-d '{"url": "https://hooks.example.com/mailinapp", "events": ["lead.hot", "booking.created"]}'
La respuesta 201 trae el id de la suscripción y su secret, que firma cada entrega. Guárdalo: no se vuelve a devolver. GET /api/v1/webhooks lista tus suscripciones y DELETE /api/v1/webhooks/{id} elimina una. Un solo nombre de evento desconocido hace que se rechace toda la solicitud. Estas rutas admiten 30 solicitudes por minuto y clave.
El contrato completo está en la especificación OpenAPI.
Leer los resultados de experimentos
Con una clave de API, tu código puede leer tus experimentos, por ejemplo para obtener las cifras en cuanto llega experiment.completed:
GET /api/v1/experimentslos lista, del más reciente al más antiguo. Filtra constatus,kind(sendojourney),projectIdojourneyId.GET /api/v1/experiments/{id}devuelve uno.GET /api/v1/experiments/{id}/resultsdevuelve el experimento con su informe completo: las mismas cifras que la exportación JSON de la página de resultados, solo datos agregados.
Estas rutas solo leen. Bloquear, lanzar, decidir y desplegar una ganadora se sigue haciendo en el panel. Admiten 60 solicitudes por minuto y clave. Interpretar los resultados de un experimento explica qué significan las cifras.