Saltar al contenido principal

Documentation Index

Fetch the complete documentation index at: https://knowledge.flowella.io/llms.txt

Use this file to discover all available pages before exploring further.

Los webhooks salientes permiten a tus sistemas reaccionar a eventos en Flowella casi en tiempo real, sin hacer polling a la API. Configuras una URL y una lista de tipos de evento, y Flowella envía un POST con un payload JSON firmado a esa URL cada vez que ocurre uno de esos eventos.

​
Configurar un webhook

Necesitas el rol Owner o Admin.
1

Abre Settings → Webhooks

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

Añade un webhook

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

Guarda el secreto de firma

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

Envía una prueba

Haz clic en Send test para enviar un payload webhook.test al instante. Comprueba que tu endpoint lo recibe y responde con un 2xx.

​
Tipos de evento

Puedes suscribirte a cualquiera de estos eventos del producto:
EventoCuándo se dispara
message.receivedHa llegado un mensaje entrante de WhatsApp desde un contacto
message.sentFlowella ha aceptado tu mensaje saliente y lo ha enviado a Meta
message.deliveredMeta confirmó que el mensaje se entregó al dispositivo del destinatario
message.readEl destinatario abrió el mensaje
message.failedMeta devolvió un fallo para el mensaje
conversation.openedUna conversación ha pasado al estado abierta
conversation.closedUna conversación se ha cerrado
optout.createdUn contacto se ha dado de baja en un canal específico
template.status_updatedMeta ha cambiado el estado de una plantilla (approved, rejected, paused, disabled)
webhook.test se envía solo cuando haces clic en Send test: no te suscribes a él de forma explícita.

​
Formato de la solicitud

Flowella envía un POST con 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>
Los payloads están limitados a 256 KB. Los objetos más grandes se resumen: usa la API para obtener el registro completo por ID si lo necesitas. 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": { "...campos específicos del evento..." }
}

​
Verificar firmas

Cada solicitud incluye una cabecera X-Flowella-Signature. El valor es el resumen hexadecimal HMAC-SHA256 del cuerpo bruto de la solicitud en UTF-8 firmado con el secreto de tu webhook. Verifica 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 en bruto del cuerpo antes de cualquier parseo JSON o reformateo por middleware del payload. Si tu framework reserializa el JSON, la firma no coincidirá.

​
Respuestas, reintentos y timeouts

  • Timeout: Flowella espera hasta 10 segundos la respuesta de tu endpoint.
  • Éxito: cualquier respuesta 2xx se trata como entrega correcta.
  • Reintentos: las entregas fallidas se reintentan hasta 3 veces con backoff.
  • Desactivación automática: si un webhook acumula 10 fallos consecutivos, Flowella lo desactiva. Tendrás que volver a activarlo desde Settings → Webhooks después de arreglar tu endpoint.
Tu endpoint debe responder lo más rápido posible: aplaza cualquier procesamiento pesado a una cola en segundo plano por tu lado.

​
Idempotencia

Los webhooks pueden reintentarse, así que el mismo evento lógico puede llegar más de una vez. Para procesarlos de forma segura:
  • Usa 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 pocas horas bastan para los reintentos).
  • Trata los duplicados como no-op.

​
Listar y gestionar entregas

Settings → Webhooks muestra los últimos intentos de entrega 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 por fallos repetidos, la misma página te permite volver a activarlo.

​
Desarrollo local

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