Saltar al contenido principal
El cuadro de diálogo New webhook con campos para el nombre, la URL del endpoint y el secreto de firma, y la lista de eventos que se envían
Un webhook saliente hace que Flowella envíe un POST HTTP a tu propio sistema cada vez que ocurre un evento elegido, por ejemplo cuando un contacto envía un mensaje de WhatsApp. Esta página explica cómo añadir, probar y gestionar endpoints de webhook en la aplicación. Para los tipos de eventos, los cuerpos de las solicitudes, las cabeceras y cómo verificar las firmas, consulta la referencia de webhooks.

​
Antes de empezar

  • Necesitas el rol Owner o Admin. Los demás roles ven Webhooks en el menú, pero la lista no se carga para ellos. Consulta Equipo y roles.
  • Necesitas una URL pública que acepte solicitudes POST con un cuerpo JSON y responda con un estado 2xx en un plazo de 10 segundos.
  • Elige un secreto de firma de al menos 8 caracteres y guárdalo donde tu controlador pueda leerlo. Flowella lo usa para firmar cada solicitud y no vuelve a mostrarlo después de guardarlo.

​
Añadir un endpoint de webhook

1

Abre Webhooks

Ve a Settings y selecciona Webhooks en el grupo Developer. Se abre la pantalla Outbound webhooks.
2

Crea un webhook nuevo

Selecciona Add webhook. Se abre el cuadro de diálogo New webhook.
3

Pon nombre al endpoint (opcional)

En Name (optional), introduce hasta 80 caracteres, por ejemplo CRM sync. El nombre aparece encima de la URL en la lista.
4

Introduce la URL del endpoint

En Endpoint URL, introduce la dirección completa a la que Flowella debe enviar los eventos. Debe cumplir las reglas de la URL.
5

Introduce tu secreto de firma

En Signing secret, escribe el secreto que elegiste, de entre 8 y 512 caracteres. Flowella no genera uno por ti.
6

Elige los eventos

En Events, marca cada evento que quieras recibir. La referencia de webhooks explica cuándo se dispara cada uno.
7

Guarda

Selecciona Create webhook. El botón no está disponible hasta que hayas introducido una URL, un secreto de al menos 8 caracteres y al menos un evento. El nuevo webhook aparece en la lista con el estado Active.

​
Reglas de la URL

Flowella comprueba la URL al guardarla y de nuevo antes de cada entrega. La URL debe:
  • Empezar por https:// o http://. http:// sin cifrar funciona, pero la carga útil viaja sin cifrar, así que usa https:// salvo en pruebas rápidas.
  • No contener nombre de usuario ni contraseña.
  • Apuntar a una dirección pública. Flowella rechaza localhost, los nombres de host que terminan en .localhost o .local, y metadata.google.internal. También rechaza los nombres de host que no se resuelven. Las direcciones privadas, de loopback, link-local y no especificadas también se rechazan, tanto si las introduces directamente como si un nombre de host apunta a ellas. Algunos ejemplos son 10.0.0.5, 127.0.0.1, 169.254.169.254, 192.168.1.10 y ::1.
  • No superar los 2.048 caracteres.
Una URL que incumple estas reglas muestra el error Webhook URL host is not allowed.

​
Enviar un evento de prueba

Usa un evento de prueba para comprobar que tu endpoint recibe y acepta solicitudes antes de que lleguen eventos reales.
  1. En la lista, selecciona el botón … al final de la fila del webhook para abrir su menú de acciones.
  2. Selecciona Send test event. Aparece una confirmación bajo la URL del webhook.
  3. Abre Delivery log desde el mismo menú. Una fila webhook.test con el Result OK significa que tu endpoint respondió con un estado 2xx.
Un evento de prueba tiene el tipo webhook.test y los data { "test": true, "sentAt": "..." }. Flowella lo envía sean cuales sean los eventos que marcaste, e incluso cuando el webhook está inactivo. La referencia de webhooks muestra el cuerpo completo.

​
Registro de entregas

Selecciona Delivery log en el menú de acciones de un webhook para ver sus últimos 50 intentos de entrega, del más reciente al más antiguo. El registro de la aplicación no muestra los cuerpos de las respuestas y no tiene botón para volver a entregar. Para leer los primeros 1.024 caracteres del cuerpo de una respuesta, o para volver a entregar un evento, usa la API de entregas de webhooks.

​
Reintentos y espera progresiva

Una entrega se completa cuando tu endpoint responde con un estado 2xx en un plazo de 10 segundos. Si no lo hace, Flowella vuelve a intentarlo de inmediato: 3 intentos en total, aproximadamente 1 segundo después del primer fallo y unos 2 segundos después del segundo. Tras el tercer intento fallido, Flowella descarta ese evento y no lo reintenta más tarde. El diagrama muestra qué ocurre con cada evento y cuándo Flowella desactiva un webhook. Cuando 10 eventos seguidos fallan en todos sus intentos, Flowella desactiva el webhook y su estado cambia a Inactive. Todos los Owners de la organización reciben una notificación en la aplicación titulada “Outbound webhook disabled”, sean cuales sean sus preferencias de notificación. Cualquier entrega correcta pone el contador a cero. Mientras un webhook está inactivo, Flowella no le envía ningún evento y no los guarda para enviarlos después. Para recuperar los eventos que te perdiste, lee el feed de eventos con GET /v1/events, que conserva los eventos durante 7 días. Consulta la referencia de webhooks.

​
Gestionar endpoints

El menú de acciones de cada fila tiene Edit, Send test event, Delivery log y Delete.

​
Editar un webhook

Selecciona Edit para abrir el cuadro de diálogo Edit webhook. Puedes cambiar:
  • Endpoint URL.
  • Events. Al menos uno debe seguir marcado.
  • Webhook active. Desmárcalo para detener las entregas durante un tiempo. Los eventos que ocurren mientras el webhook está inactivo no se envían después.
  • New signing secret. Déjalo en blanco para conservar el secreto actual. Un secreto nuevo debe tener al menos 8 caracteres; de lo contrario, Flowella conserva el actual.
Selecciona Save para aplicar los cambios.
Un secreto nuevo guardado en la aplicación sustituye al anterior de inmediato, así que las solicitudes firmadas con el secreto anterior dejan de valer al momento. Para cambiar de secreto sin perder eventos, rota el secreto con la API. Durante las 24 horas posteriores a una rotación, cada solicitud lleva además una firma hecha con el secreto anterior en la cabecera X-Flowella-Signature-Previous. Consulta Rotar un secreto de firma.
El cuadro de diálogo de edición también muestra Name (optional), pero un nombre cambiado no se guarda. Para renombrar un webhook, usa PATCH /v1/webhooks/{id} con un name.

​
Volver a activar un webhook

Después de que Flowella desactive un webhook, corrige primero el problema en tu endpoint. Después:
  1. Selecciona Edit, marca Webhook active y selecciona Save.
  2. Selecciona Send test event y comprueba que el Delivery log muestra OK.
No te saltes la prueba. Al activar el webhook en la aplicación, su contador de fallos se queda en 10, así que un solo evento fallido lo vuelve a desactivar. Una entrega correcta, como un evento de prueba que funciona, pone el contador a cero. La llamada a la API POST /v1/webhooks/{id}/reactivate activa el webhook y pone el contador a cero en un solo paso.

​
Eliminar un webhook

Selecciona Delete y confirma Delete en el cuadro de diálogo Delete webhook?. Flowella elimina el endpoint y su historial de entregas. Esta acción no se puede deshacer.

​
Solución de problemas

Introduce una URL de endpoint, un secreto de firma de al menos 8 caracteres y marca al menos un evento.
La URL incumple una de las reglas de la URL. Comprueba que el nombre de host se resuelve públicamente y no apunta a una dirección privada o local. Para hacer pruebas contra tu propio ordenador, exponlo mediante un túnel público y usa la dirección del túnel.
Solo los Owners y Admins pueden ver y gestionar webhooks. Pide a un Owner o Admin que configure el webhook por ti. Los roles no se pueden cambiar en la aplicación: consulta Cambiar el rol de alguien.
Comprueba que el webhook está Active y que el evento está marcado en Events. Algunos eventos solo se disparan en determinados casos: por ejemplo, los eventos de contacto solo se disparan con cambios hechos a través de la API, y optout.created no se dispara por ahora con la primera baja de un contacto en un número. La referencia de webhooks enumera cada caso. Algunas entregas se omiten sin entrada en el registro. Esto ocurre con los eventos de más de 256 KB y con las entregas a una URL que ya no cumple las reglas de la URL, por ejemplo tras un cambio de DNS.
Comprueba la columna HTTP. Un guion significa que tu endpoint no respondió en 10 segundos o no se pudo alcanzar. Responde con un estado 2xx en cuanto recibas la solicitud y haz cualquier trabajo lento en segundo plano.
Calcula la firma sobre el cuerpo sin procesar de la solicitud, antes de cualquier análisis de JSON, usando exactamente el secreto que guardaste. Consulta Verificar firmas.

​
Relacionado

Referencia de webhooks

Tipos de eventos, cuerpos, cabeceras y comprobación de firmas.

Claves API

Crea la clave que necesitas para gestionar webhooks a través de la API.

Developer hub

Solicitudes recientes a la API, guías rápidas y el sandbox de la API.

Notificaciones

Dónde aparece la alerta Outbound webhook disabled.
Última modificación el 24 de octubre de 2026