Saltar al contenido principal
Los webhooks salientes permiten a sus sistemas reaccionar a eventos en Flowella casi en tiempo real, sin sondear la API. Se configura una URL y una lista de tipos de eventos, y Flowella envía una carga JSON firmada a esa URL cada vez que se produce uno de esos eventos.

​
Configuración de un webhook

Necesitas el rol Owner o Admin.
1

Abra Ajustes → Webhooks

En la aplicación Flowella, ve a Configuración → Webhooks.
2

Añadir un webhook

Haz clic en Añadir webhook, pega la URL HTTPS pública de tu endpoint y elige los tipos de eventos que quieres recibir.
3

Guardar el secreto de firma

Flowella genera un secreto de firma único para el webhook. Cópialo: lo utilizarás para verificar las solicitudes entrantes.
4

Enviar una prueba

Haz clic en Enviar prueba para enviar inmediatamente una carga útil webhook.test. Comprueba que tu endpoint lo ha recibido y ha respondido con un 2xx.

​
Tipos de eventos

Puede suscribirse a cualquiera de estos eventos de producto:

​
Evento ## Cuando se dispara

| --- | --- | | message.received | Ha llegado un mensaje entrante WhatsApp de un contacto | | message.sent | Flowella ha aceptado su mensaje saliente. | message.sent | Flowella ha aceptado su mensaje saliente y lo ha enviado a Meta | Meta | message.delivered | Meta ha confirmado la entrega del mensaje al dispositivo del destinatario | message.read | message.read El destinatario abrió el mensaje | message.failed | message.failed | Meta devolvió un fallo para el mensaje | conversation.opened | conversation.opened | Una conversación ha pasado al estado abierto | conversation.closed | conversation.closed | Se ha cerrado una conversación | optout.created | optout.created | Un contacto se ha dado de baja en un canal específico | template.status_updated | template.status_updated | Meta ha cambiado el estado de una plantilla (aprobada, rechazada, en pausa, desactivada) | optout.created webhook.test sólo se envía cuando haces clic en Enviar prueba - no te suscribes a él explícitamente.

​
Formato de solicitud

Flowella envía un cuerpo JSON a tu URL con estas cabeceras: 
POST https://your-endpoint.example.com/flowella
Content-Type: application/json
User-Agent: Flowella-Webhooks/1
X-Flowella-Signature: <hex digest>
Las cargas útiles tienen un límite de 256 KB. Los objetos de mayor tamaño se resumen: utilice la API para obtener el registro completo por ID si lo necesita. La forma del cuerpo varía según el evento, pero siempre incluye: 
{
  "event": "message.delivered",
  "timestamp": "2025-01-15T14:30:00.000Z",
  "organizationId": "clxxxxxxxxxxxxxxxxxxxxxxxx",
  "data": { "...event-specific fields..." }
}

​
Verificación de firmas

Cada petición incluye una cabecera X-Flowella-Signature. El valor es el HMAC-SHA256 hex digest del raw UTF-8 request body cifrado con el secreto de firma de tu webhook. Verificar antes de procesar: 
import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, signatureHeader, secret) {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(signatureHeader, "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

import hmac, hashlib

def verify(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header)
Firma siempre sobre los bytes del cuerpo en bruto antes de que cualquier parseo JSON o middleware reformatee la carga útil. Si tu framework reserializa JSON, la firma no coincidirá.

​
Respuestas, reintentos y tiempos de espera

  • Tiempo de espera**: Flowella espera hasta 10 segundos a que su endpoint responda.
  • Success: cualquier respuesta de 2xx se considera una entrega correcta.
  • Reintentos**: las entregas fallidas se reintentan hasta 3 intentos con backoff.
  • Desactivación automática**: si un webhook acumula 10 fallos consecutivos, Flowella lo desactiva. Tendrás que volver a activarlo desde Configuración → Webhooks después de arreglar tu endpoint.
Su punto final debe volver lo más rápido posible - aplazar cualquier procesamiento pesado a una cola de fondo de su lado.

​
Idempotencia

Los webhooks pueden ser reintentados, por lo que el mismo evento lógico puede llegar más de una vez. Para procesar con seguridad:
  • Utilice el data.id del evento (o una clave derivada como event + data.messageId) como clave de idempotencia.
  • Mantén una caché de corta duración de las claves procesadas (unas horas son suficientes para reintentos).
  • Tratar los duplicados como no-ops.

​
Listado y gestión de entregas

Configuración → Webhooks muestra los intentos de entrega recientes por webhook, incluyendo:
  • Marca de tiempo
  • Tipo de evento
  • Estado de la respuesta
  • Un cuerpo de respuesta truncado (hasta ~1 KB) para depuración
Si un webhook se desactiva debido a fallos repetidos, la misma página le permite volver a activarlo.

​
Desarrollo local

La forma más sencilla de desarrollar con webhooks localmente es enviar un túnel público (por ejemplo, ngrok o Cloudflare Tunnel) a tu servidor de desarrollo y apuntar la URL del webhook al host del túnel. Utiliza Send test para disparar payloads bajo demanda sin esperar a la actividad real de WhatsApp.
¿Necesitas reaccionar a eventos que no están en la lista? Dínoslo en support - añadimos eventos a medida que los clientes nos los piden.

​
Relacionados

Configuración → Webhooks

Configurar puntos finales, secretos de firma y reintentos en la aplicación.

Introducción a la API

Autenticación, errores, paginación y límites de velocidad para la API REST.

Claves API

Crea y rota los tokens portadores que tu endpoint pueda necesitar.

Eventos de notificación

Los mismos eventos entregados en el feed in-app y el correo electrónico.
Última modificación el 15 de junio de 2026