Webhooks
Avisos en tiempo real para tu sistema: endpoints, eventos y entregas.
Para qué sirve
Un webhook avisa a tu sistema, mediante una solicitud HTTPS firmada, cada vez que ocurre algo en Postal: un correo entregado, un rebote, una queja, un correo recibido, un contacto nuevo. Es la forma de reaccionar en tiempo real en lugar de consultar la API.
Cuándo usarlo: para actualizar tu base de datos con el resultado de los envíos, desactivar las direcciones que rebotaron, abrir un ticket cuando llega un correo y avisar al equipo cuando se pausan los envíos.
#Lista de webhooks
Dónde está: Desarrolladores › Webhooks. Dirección: app.postal.so/webhooks.
| Campo | Qué hace |
|---|---|
| Añadir webhook | Abre el alta: la URL del endpoint y los Eventos. |
| URL del endpoint | Debe ser HTTPS y responder con 2xx en un máximo de 15 segundos. Postal envía un POST firmado por cada evento elegido. |
| Eventos | Marca los que quieras recibir (consulta Eventos). Seleccionar todo / Deseleccionar todo se aplican a todos, y hay un par igual en cada grupo. El contador muestra N de M seleccionados. |
| Columna | Qué muestra |
|---|---|
| Endpoint | La URL (enlace al detalle). |
| Eventos | Cuántos eventos tiene suscritos el webhook. |
| Estado | Activo; Pausado (por alguien del equipo); o Desactivado por fallos (Postal lo desactivó tras 5 días seguidos sin ninguna entrega correcta). |
| Creado el | La fecha de creación. |
Mira también: Webhooks (guía) · Webhooks (API).
#Eventos y detalle del webhook
Eventos a los que puedes suscribirte
| Grupo | Eventos |
|---|---|
| E-mails | email.sent (Enviado), email.delivered (Entregado), email.delivery_delayed (Entrega retrasada), email.bounced (Rebotado), email.complained (Marcó como spam), email.opened (Abierto), email.clicked (Clic en enlace), email.replied (Respondido), email.failed (Fallido), email.scheduled (Programado), email.suppressed (Suprimido) y email.received (Recibido, en los buzones de entrada). |
| Dominios | domain.created, domain.updated y domain.deleted. |
| Supresiones | suppression.added (Añadida) y suppression.removed (Quitada). |
| Contactos | contact.created, contact.updated, contact.deleted, contact.segment_entered (Entró en un segmento dinámico) y contact.segment_exited (Salió de un segmento dinámico). |
| Formularios | form.submitted (Suscripción recibida). |
| Campañas | broadcast.sent (Envío finalizado). |
| Buzón de entrada | inbox.thread.created, inbox.thread.updated, inbox.thread.deleted y inbox.draft.created (Borrador de IA creado). |
| Envío | sending.paused (Envío pausado) y sending.resumed (Envío reanudado), para avisar al equipo al instante. |
El formato del cuerpo de cada evento está en Webhooks › Payload.
Detalle de un webhook
Al hacer clic en un webhook se abre su página. En la cabecera:
| Botón | Qué hace |
|---|---|
| Enviar evento de prueba | Dispara un evento webhook.test al endpoint (Evento de prueba enviado). Aparece en las entregas con la etiqueta Prueba. |
| Reactivar | Solo en un webhook Desactivado por fallos: vuelve a enviar. Antes, comprueba que el endpoint esté en línea y responda 2xx. |
| Pausar / Activar | Interrumpe y reanuda los envíos sin borrar nada. |
| Editar | Cambia la URL y los eventos. |
| Quitar webhook | El icono de la papelera. El endpoint deja de recibir eventos y se elimina el historial de entregas. |
| Parte | Qué es |
|---|---|
| Avisos | En un webhook activo con entregas fallidas, Las entregas fallan desde ...: si ninguna tiene éxito en 5 días, el endpoint se desactiva y los propietarios y administradores del equipo reciben un correo electrónico. Una vez desactivado, Desactivamos este endpoint el .... |
| Secreto de firma | El secreto whsec_... para validar los encabezados webhook-signature (o svix-signature) de las solicitudes. Los botones Mostrar secreto/Ocultar secreto y Copiar secreto. Generar nuevo cambia el secreto: el actual deja de funcionar de inmediato, así que actualiza tu sistema justo después. |
| Eventos suscritos | La lista de los eventos que recibe ese endpoint. |
| Ignorar los cambios de contactos que vengan de | Protección contra bucles: no se envían los eventos de contacto cuyo cambio provino de un origen de la lista (por ejemplo, el propio sistema que recibe este webhook y que también escribe en Postal). |
| Entregas | El historial de los eventos enviados, durante 30 días. |
Entregas
| Columna | Qué muestra |
|---|---|
| Evento | El tipo de evento. |
| Estado | Pendiente, Reintentando (con próximo ... que indica cuándo), Entregado o Fallido. |
| Intentos | Cuántas veces lo intentó Postal. |
| Creado el | Cuándo se generó el evento. |
| Reenviar | Vuelve a disparar ese evento. |
Al hacer clic en una entrega se abren los intentos: el código HTTP que devolvió tu endpoint (o Sin respuesta), la hora, la duración en milisegundos y el cuerpo de la respuesta o el error. Las respuestas distintas de 2xx se reenvían automáticamente durante unas 27 horas (8 intentos), siempre con el mismo webhook-id, para que tu sistema pueda tratar las repeticiones.
Consejo
Comprueba la firma de cada solicitud y responde 2xx rápido: haz el trabajo pesado después, en una cola. Consulta el paso a paso en Firma.
Mira también: Eventos (guía) · Firma · Intentos · Reenviar (API).