Crear y gestionar webhooks
Para todos los usuarios
Un webhook avisa a su sistema en el momento en que ocurre un evento con un correo, por ejemplo una entrega, un rebote, una apertura, un clic o una baja. En lugar de consultar la API periódicamente, su sistema recibe cada evento en la URL que usted indique.
La pantalla está en Webhooks, dentro de la sección Configuración del panel. La documentación para integradores explica cómo procesar los eventos en su sistema: cómo verificar la firma y qué trae cada tipo.
Antes de empezar
- Necesita acceso a la app Mail en esta instancia. Con el rol Usuario puede ver el listado, pero no aparecen los controles. Para crear, editar, probar, rotar el secreto de firma o eliminar un webhook necesita el rol Administrador en la app Mail.
- Su plan define cuántos webhooks puede tener. El contador aparece junto al botón de crear, y los webhooks pausados también ocupan cupo.
- Necesita un endpoint ya disponible: una URL https que resuelva a una dirección pública de internet y que conteste en menos de 10 segundos.
Crear un webhook
- Abra Configuración → Webhooks y pulse Crear webhook.
- Complete los campos:
- Nombre: una etiqueta para reconocerlo (por ejemplo
CRM de ventas). - URL del endpoint: la dirección que recibirá los eventos.
- Eventos: los tipos de evento que recibirá (ver Elegir los eventos).
- Activo: déjelo encendido para empezar a recibir entregas de inmediato.
- Nombre: una etiqueta para reconocerlo (por ejemplo
- Confirme. La plataforma muestra el secreto de firma una sola vez: guárdelo antes de cerrar la ventana.
Guardar el secreto de firma
Al crear el webhook, la plataforma muestra el secreto de firma una única vez. Cópielo y guárdelo de inmediato: al cerrar la ventana ya no es posible volver a verlo. Su sistema lo necesita para comprobar que cada entrega viene realmente de Fidelizador.
Si lo pierde, no hace falta crear un webhook nuevo: use Rotar secreto para generar otro (ver Rotar el secreto).
Al rotar, los usuarios con rol Administrador en la app Mail reciben un correo con la fecha en que el secreto anterior deja de firmar. Ese correo no incluye el secreto nuevo, solo el plazo.
Elegir los eventos
Puede dejar Todos los eventos, la opción por defecto, o marcar solo los que le interesan. Todos los eventos incluye además los tipos que se agreguen más adelante. Estos son los eventos:
| Evento | Cuándo llega |
|---|---|
| Correo entregado | El servidor del destinatario aceptó el correo |
| Rebote | El correo no pudo entregarse |
| Descartado | La plataforma no llegó a enviarlo (por ejemplo, un destinatario dado de baja) |
| Apertura | El destinatario abrió el correo |
| Clic | El destinatario hizo clic en un enlace |
| Baja | El destinatario se desuscribió |
| Re-suscripción | Un contacto dado de baja volvió a suscribirse |
| Queja por abuso | El destinatario marcó el correo como spam |
Marque solo lo que su sistema procesa. Aperturas y clics son, con diferencia, los eventos más numerosos: si no los usa, dejarlos fuera le ahorra tráfico a su endpoint.
Probar el endpoint
Enviar evento de prueba envía un único evento, firmado igual que uno real, y abre una ventana con el intercambio completo:
- Lo que se envió — los headers, incluida la firma, y el cuerpo exacto que viajó.
- Lo que respondió su endpoint — el código, cuánto tardó, sus headers y su respuesta.
Si su sistema rechaza la entrega, el motivo que devuelve aparece en la segunda parte, la respuesta de su endpoint. Después de corregirlo, puede repetir la prueba desde la misma ventana.
Si su endpoint no respondió, la ventana indica el motivo: que no contestó dentro de 10 segundos, que no fue posible conectar, o que la URL dejó de resolver a una dirección pública.
La prueba no se reintenta y no cuenta como fallo: no afecta el estado del webhook ni su historial de entregas.
Leer el estado y las entregas
Cada webhook muestra su Estado y sus Entregas.
Estado indica si está recibiendo entregas:
| Estado | Qué significa |
|---|---|
| Activo | Recibe entregas normalmente |
| Pausado | Usted lo pausó |
| Pausado con un rayo | La plataforma lo pausó porque su endpoint falló de forma persistente. Pase el cursor sobre la etiqueta para ver cuándo |
Entregas muestra cómo respondió su endpoint a los avisos de eventos: si el último llegó bien, cuántos fallos consecutivos acumula, desde cuándo falla y qué código devolvió la última vez.
Un webhook Activo con fallos acumulados sigue recibiendo entregas: es la señal de que algo falla en su endpoint y de que conviene revisarlo antes de que la plataforma lo pause.
Avisos por correo
La plataforma avisa por correo cuando un endpoint falla. Los avisos llegan a los usuarios de la instancia con rol Administrador en la app Mail, y son dos:
- Tras una hora de fallos continuos. Indica desde cuándo falla el endpoint, con qué código respondió la última vez y dos fechas límite: a partir de cuándo empiezan a perderse eventos y cuándo se pausará el webhook. Una sola entrega exitosa cancela las dos fechas.
- Cuando la plataforma pausa el webhook, si el endpoint sigue sin responder.
Cada aviso se envía una sola vez y llega dentro de la hora siguiente al hecho. Una pausa hecha por usted desde el panel no genera aviso.
Cuándo lo pausa la plataforma
Si un endpoint acumula 20 fallos seguidos a lo largo de 72 horas o más sin ninguna entrega exitosa, la plataforma lo pausa sola. El listado muestra además un aviso arriba de la tabla.
Los eventos que ocurren mientras el webhook está pausado se pierden: no se entregan después. Por eso conviene corregir el endpoint cuanto antes.
Pausar y reanudar
Pausar detiene las entregas sin eliminar el webhook, y conserva la configuración, los eventos elegidos y el secreto. Es útil durante un mantenimiento de su sistema. La plataforma pide confirmación porque, igual que en la pausa automática, los eventos de ese lapso se pierden.
Reanudar lo vuelve a poner en servicio sin pedir confirmación, porque no se pierde nada. También reinicia el conteo de fallos, igual que corregir la URL, así que un fallo aislado no lo vuelve a pausar de inmediato.
Rotar el secreto
Rotar secreto genera un secreto nuevo y lo muestra una sola vez, como al crear el webhook. Durante las 24 horas siguientes cada entrega se firma con el secreto nuevo y con el anterior, de modo que puede actualizar su sistema dentro de ese plazo sin que se rechacen entregas. El listado indica hasta cuándo firma el anterior.
Si el secreto anterior quedó expuesto, marque la opción El secreto anterior quedó expuesto al rotar: el anterior deja de firmar de inmediato, sin las 24 horas de transición. Desde ese momento su sistema rechazará las entregas mientras siga verificando con el secreto anterior, así que actualícelo cuanto antes.
Eliminar un webhook
Eliminar es definitivo: el endpoint deja de recibir eventos y los reintentos pendientes se descartan. Si solo quiere una interrupción temporal, use Pausar.
Dudas frecuentes
¿Puedo usar una URL http?
No. La URL debe usar https y resolver a una dirección pública de internet; una dirección de red interna es rechazada.
¿Puedo recuperar el secreto de firma después?
No, pero puede rotarlo para obtener uno nuevo sin tocar el resto de la configuración.
¿Qué pasa si mi endpoint deja de responder por un tiempo?
La entrega se reintenta durante unas 27 horas. Pasado eso se descarta, y no hay reenvío manual.
¿Por qué me llegó el mismo evento dos veces?
Puede ocurrir, por ejemplo si su endpoint procesó la entrega pero su respuesta no alcanzó a llegar. Cada evento trae un identificador estable para que su sistema descarte duplicados.
¿Los eventos llegan en orden?
No está garantizado. Use la fecha y hora de cada evento para ordenarlos.
¿Por qué no veo Webhooks en el menú?
Depende de su rol en la instancia: sin acceso a la app Mail en esta instancia, la entrada no aparece.
¿Por qué no puedo crear más webhooks?
Llegó al cupo de su plan, y los webhooks pausados también cuentan. Elimine uno que ya no use. También puede pulsar Mejorar plan en el aviso Límite del plan alcanzado, que aparece al intentar crear uno.
Más preguntas en Preguntas frecuentes.