Webhooks: recibir los eventos de correo en tu sistema

5 min de lectura65
Copiar para la IA:

El webhook es el camino de vuelta de la integración: WiseData Mail avisando a tu sistema qué pasó con cada correo — entregado, rebotado, abierto, con clic, dado de baja. Con él, la tienda en línea de Casa Moura Cafés sabe que el pedido-confirmado de un cliente rebotó y puede pedirle otro correo en su próxima visita.

El registro se hace solo en el panel, en Configuración › Webhooks, y el historial está en Configuración › Eventos webhook. Las dos pestañas son del Propietario. Si no aparecen para ti, habla con soporte.

Registrar un webhook

Haz clic en Nuevo webhook y completa:

  • Dirección: empezando por https:// y alcanzable desde internet, como https://casamoura.com.br/webhooks/mail. Una dirección que apunta dentro de una red interna se rechaza, y las redirecciones no se siguen: tu servidor tiene que responder en la misma dirección registrada.
  • Descripción: qué sistema recibe estos eventos.
  • Eventos suscritos: marca al menos uno. Dos tienen aviso propio: Aceptado por el proveedor llega uno por mensaje enviado (alto volumen, solo vale si mides el embudo), y los eventos de dominio (Dominio listo para enviar, El dominio no quedó listo, El dominio dejó de estar listo) hablan del dominio, no de un mensaje, y llegan sin correo de destinatario; tu receptor tiene que aceptarlo.
  • De dónde recibir: aparece con espacios de envío en la cuenta. Sin ninguno marcado, el webhook recibe la cuenta completa, incluidos los espacios creados después. Marcando espacios, recibe solo los de ellos, sin los de la cuenta principal.
  • Recibir eventos: apagado, el webhook queda Pausado.

Un webhook nuevo empieza a recibir desde el momento en que se crea. Los eventos anteriores al registro no se envían.

El secreto aparece una vez

Al guardar, la ventana Webhook creado muestra el secreto. Cópialo en el momento: no vuelve a aparecer. Cada lote llega firmado, y con ese secreto tu sistema verifica la firma antes de confiar en el contenido. Un lote cuya firma no coincide debe rechazarse.

Cómo llegan los eventos

  • En lotes: varios eventos por llamada, no uno por vez. En una campaña grande, eso le ahorra a tu servidor miles de llamadas.
  • Responde 2xx, y rápido. Cualquier otra respuesta cuenta como fallo, y el lote se reenvía automáticamente. Guarda el lote y procésalo después; no hagas que WiseData Mail espere tu procesamiento.
  • Prepárate para recibir el mismo lote dos veces. Un lote reenviado llega igual al original; tu receptor debe ignorar lo que ya procesó.
  • No es tiempo real. Hay algunos instantes entre el evento y la entrega: no uses el webhook como disparador de algo que alguien está esperando en pantalla.

Activo, pausado y desactivado por fallos

  • Activo: recibiendo.
  • Pausado: apagaste Recibir eventos. Vuelve a encenderlo desde la edición.
  • Desactivado por fallos: después de una serie de lotes fallidos, WiseData Mail apaga el webhook por sí solo y el Propietario recibe un correo. La lista muestra cuántos lotes fallaron seguidos y la fecha de la última entrega exitosa.

Antes de hacer clic en Reactivar, corrige tu servidor; si no, vuelve a fallar. Y ten en cuenta que los eventos del período apagado no se reenvían: el historial muestra lo que quedó atrás. Guardar una edición del webhook también pone en cero el conteo de fallos.

Los botones de cada webhook

  • Probar: llama a tu dirección en el momento y muestra lo que respondió (código y tiempo). La prueba no entra en el historial y no cuenta para el apagado automático.
  • Historial: abre Eventos webhook ya filtrado en este webhook.
  • Rotar secreto: genera un secreto nuevo y el actual deja de valer de inmediato. No hay período con los dos válidos: entre la rotación y la instalación del nuevo, tu servidor rechazará las entregas. Los lotes que fallen en ese intervalo se reenvían automáticamente, así que instala el nuevo secreto pronto.
  • Editar: dirección, descripción, eventos, espacios y el interruptor.
  • Eliminar: tu sistema deja de recibir al instante, y el historial de entregas se borra con él. Si solo perdiste el secreto, prefiere Rotar secreto: el historial se mantiene.

El historial de entregas

En Eventos webhook, elige el webhook (si hay más de uno) y mira cada lote: Cuándo, Estado (Pendiente, Entregado o Falló), cuántos Eventos y cuántos Intentos.

Ver abre el detalle del lote:

  • Cuerpo enviado: exactamente lo que se firmó. Cuando la firma no coincide de tu lado, compáralo con lo que recibió tu servidor: la diferencia suele estar en que el cuerpo se leyó ya convertido y no tal como llegó.
  • Intentos: cada uno con el código que respondió tu servidor, el tiempo y un fragmento de la respuesta. sin respuesta significa que el servidor no respondió a tiempo o ni siquiera fue alcanzado: el problema está antes de tu código.

Un lote que no se entregó tiene el botón Reenviar, en la tabla y en el detalle. Úsalo después de corregir tu servidor para recuperar lo que falló.

Para quien integra

Cada evento trae el tipo, el correo del destinatario, el mensaje, la campaña (vacía en el transaccional), el espacio de donde salió y, cuando el envío se hizo por la API, las etiquetas y los metadatos que envió tu sistema. Los eventos simulados en la Bandeja de prueba llegan a la misma dirección, marcados como prueba: ignóralos en el receptor de producción, o un rebote simulado se convierte en la baja de un cliente real.

Adónde ir después

  • Bandeja de prueba: simular un rebote o un clic y ver llegar el webhook.
  • Claves de API: el camino de ida de la integración.
  • Espacios de envío: recibir eventos solo de algunos espacios.

En resumen: registra una dirección https que responda 2xx rápido, marca solo los eventos que usa tu sistema, guarda el secreto para verificar la firma de cada lote, maneja los lotes repetidos, corrige el servidor antes de reactivar un webhook desactivado por fallos y usa el historial para descubrir lo que no llegó.

¿Te resultó útil este artículo?