Webhooks

La sección Webhooks de Floogos centraliza la administración de todos los endpoints HTTP que disparan workflows. Desde aquí puedes ver el estado de tus webhooks, asignar políticas de seguridad y analizar el tráfico de acceso.

Indicadores principales (KPIs)

En la parte superior de la página se muestran 4 tarjetas de resumen calculadas en tiempo real:

Indicador	Descripción
Total Webhooks	Número de webhooks configurados en tu cuenta
Llamadas 24h	Suma de todas las peticiones recibidas en las últimas 24 horas
Bloqueados 24h	Peticiones rechazadas por políticas de seguridad en las últimas 24 horas
Con política	Webhooks que tienen una política de seguridad asignada, con el porcentaje protegido

Lista de webhooks

La tabla muestra un resumen de cada webhook con las siguientes columnas:

Columna	Descripción
Workflow	Nombre del workflow asociado con acceso directo al editor
Node	Identificador del nodo Webhook dentro del workflow
Seguridad	Badges activos: `Rate`, `IP`, `HMAC` según la política asignada
24h	Llamadas recibidas y bloqueadas en las últimas 24 horas
⚙	Botón para abrir el panel lateral de detalle

Panel lateral (drawer)

Al pulsar ⚙ en cualquier webhook se abre un panel lateral con tres secciones:

URLs

Muestra las dos URLs del webhook listas para copiar:

LIVE (verde) — URL de producción: .../webhooks/<hash>
DEV (azul) — URL de desarrollo: .../webhooks-dev/<hash>

Política de seguridad

Selector para asignar una política existente al webhook. Al cambiar la selección, los badges de seguridad de la tabla se actualizan de inmediato sin recargar la página.

Si el webhook no tiene política asignada, aparece un aviso de advertencia informando que cualquier IP puede llamarlo sin restricciones.

El botón Nueva abre el modal de creación de políticas directamente.

Estadísticas rápidas (30 días)

Cuatro métricas del período y un gráfico de área diario:

Métrica	Descripción
Total	Peticiones totales en 30 días
Bloqueados	Suma de bloqueados y rate-limited
Tasa éxito	`allowed / total × 100`
Avg ms	Tiempo medio de ejecución del workflow

Bajo el gráfico se muestran las últimas 8 llamadas de los últimos 7 días con IP, estado, motivo de bloqueo y duración.

El botón Insights en la cabecera del panel navega a la página de insights completa.

Webhooks huérfanos

Un webhook queda huérfano cuando pierde su asociación con un workflow válido. Ocurre en dos casos:

Workflow borrado — se eliminó el workflow al que apuntaba el webhook.
Nodo removido — el workflow existe pero el nodo Webhook/FormTrigger que lo disparaba ya no está en el flujo.

Los webhooks huérfanos no aparecen en la lista principal (que solo muestra los asociados a un workflow existente), por lo que quedan ocultos en la base de datos sin forma de gestionarlos desde la tabla normal. Ya no disparan ninguna ejecución, pero conviene limpiarlos.

Detectar y limpiar

El botón Detectar huérfanos, en la barra superior de la sección Webhooks, abre un diálogo que lista todos los webhooks huérfanos de tu cuenta:

Columna	Descripción
Motivo	`Workflow borrado`, `Nodo removido` o `Sin workflow`
Workflow ID	Identificador del workflow al que apuntaba
Nodo	Nodo que lo disparaba (ej. `FormTrigger_2`)
Hash	Hash único del webhook
Creado	Fecha de creación

Desde el diálogo puedes:

Seleccionar webhooks individualmente (o todos con el interruptor de la cabecera) y pulsar Eliminar seleccionados.
Eliminar todos los huérfanos de una vez.

La limpieza es segura: el servidor revalida cada webhook antes de borrarlo y nunca elimina uno que tenga un workflow válido, aunque su hash aparezca en la petición. Cuando no quedan huérfanos, el diálogo muestra una confirmación en verde.

Políticas de seguridad

Las políticas son configuraciones reutilizables que puedes asignar a uno o varios webhooks. Se gestionan desde el botón Nueva política de seguridad.

Nombre automático

El nombre de la política se genera automáticamente según la configuración activa:

100 req/60s — rate limiting
IP whitelist o IP blacklist — filtrado de IPs
HMAC — firma habilitada
Horario 08:00–20:00 — restricción horaria

Si el usuario edita el nombre manualmente, deja de actualizarse automáticamente. El botón ↺ restablece el nombre automático.

Rate Limiting

Limita el número de peticiones que puede recibir el webhook en una ventana de tiempo.

Campo	Descripción
Máx. peticiones	Número máximo de peticiones permitidas en la ventana
Ventana (seg)	Duración de la ventana en segundos
Scope	`Por IP` (contador independiente por IP) o `Global` (contador compartido)

Cuando se supera el límite, el webhook devuelve 429 Too Many Requests con el header retry_after indicando los segundos que faltan para poder reintentar.

El rate limiter opera en memoria del servidor. Es ideal para proteger endpoints de abusos sin necesidad de Redis u otras dependencias externas.

Filtrado de IPs

Permite o bloquea peticiones según la IP de origen, con soporte para rangos CIDR.

Modo	Comportamiento
Desactivado	Sin restricciones de IP
Lista blanca	Solo se permiten las IPs/rangos de la lista
Lista negra	Se bloquean las IPs/rangos de la lista

Formato de la lista: una IP o rango CIDR por línea. Ejemplos:

192.168.1.10
10.0.0.0/8
172.16.0.0/12

Las peticiones bloqueadas por IP devuelven 403 Forbidden con motivo ip_blacklist.

Firma HMAC-SHA256

Verifica que el cuerpo de cada petición esté firmado con un secret compartido. Diseñado para servicios que soportan firmas de payload (GitHub, Stripe, etc.).

Campo	Descripción
Secret key	Clave secreta compartida con el servicio externo
Header	Nombre del header que contiene la firma (por defecto `X-Floogos-Signature`)

El botón ⚡ genera una clave aleatoria de 32 bytes en hexadecimal directamente en el navegador (Web Crypto API), sin transmitirla al servidor hasta guardar.

Formato de firma esperado:

sha256=<hmac_hex_del_body>

Las peticiones sin firma o con firma incorrecta devuelven 403 Forbidden con motivo signature_invalid.

Restricción horaria

Permite que el webhook solo acepte peticiones en días y horas específicos.

Campo	Descripción
Desde / Hasta	Rango horario en formato `HH:MM`
Timezone	Zona horaria para evaluar el horario (por defecto `UTC`)

Las peticiones fuera del horario devuelven 403 Forbidden con motivo schedule_blocked.

Insights de acceso

La página de Insights de un webhook está disponible en /webhooks/:id/insights y ofrece un análisis completo del tráfico de acceso.

Selector de período

El período de análisis es configurable: 7, 14, 30, 60 o 90 días. Al cambiarlo, todos los gráficos y tablas se actualizan automáticamente.

KPI cards (7 métricas)

Métrica	Descripción
Total llamadas	Peticiones totales en el período con sparkline diario
Permitidas	Peticiones con status `allowed`
Bloqueadas	Suma de `blocked` + `rate_limited`
Tasa de éxito	`allowed / total × 100` con sparkline
Errores	Peticiones con status `error` (fallo en ejecución del workflow)
Tiempo medio	Tiempo promedio de ejecución en milisegundos
Pico tiempo	Tiempo máximo registrado en el período

Gráfico de volumen diario

Gráfico de área que muestra la evolución diaria de peticiones totales (naranja) y bloqueadas (rojo) a lo largo del período seleccionado.

Top 10 IPs

Lista de las 10 IPs con mayor volumen de llamadas, con:

Barra de progreso relativa al máximo
Contador de llamadas totales
Contador de llamadas bloqueadas (si aplica)

Motivos de bloqueo

Distribución de bloqueos por motivo con barras de progreso:

Motivo	Descripción
`Rate limit`	Superó el límite de peticiones por ventana
`IP bloqueada`	IP en lista negra o fuera de lista blanca
`Firma inválida`	Header HMAC ausente o incorrecto
`Método no permitido`	Método HTTP no incluido en los permitidos
`Payload grande`	Body supera el límite de `max_payload_bytes`
`Fuera de horario`	Petición recibida fuera del horario configurado
`Error ejecución`	El workflow arrojó un error durante la ejecución

Métodos HTTP

Desglose de las peticiones por método HTTP (GET, POST, etc.) con porcentaje relativo.

Prod vs Dev

Distribución de llamadas entre el endpoint de producción (/webhooks/<hash>) y el de desarrollo (/webhooks-dev/<hash>).

Log de accesos

Tabla paginada con el historial completo de peticiones. Soporta hasta 100 filas por página.

Columna	Descripción
Fecha	Timestamp de la petición
IP	IP de origen
Método	GET / POST
Estado	`allowed` (verde), `rate_limited` (amarillo), `blocked` / `error` (rojo)
Motivo	Razón de bloqueo si aplica
Código	Código HTTP devuelto
Duración	Tiempo de ejecución del workflow en ms
Tamaño	Tamaño del payload en KB
Entorno	`PROD` o `DEV`

Códigos de respuesta

Respuestas de seguridad (antes de ejecutar el workflow)

Estos códigos se devuelven cuando la política de seguridad rechaza la petición, independientemente del entorno (PROD o DEV):

Código	Motivo
`403`	IP bloqueada, firma inválida o fuera de horario
`405`	Método HTTP no permitido
`413`	Payload supera el tamaño máximo
`429`	Rate limit superado (incluye `retry_after`)

Respuestas de ejecución

El body de respuesta varía según el entorno y el nodo final del workflow:

Escenario	PROD	DEV
Termina con webresponse	Código, headers y body personalizados	Igual que PROD
Sin webresponse — éxito	`{"status": 200}`	Resultado completo del workflow
Sin webresponse — error	`{"status": 500}`	`{"error": "mensaje del error"}`

La URL de producción nunca expone datos internos del workflow ni mensajes de error en texto plano. Para respuestas HTTP completamente personalizadas utiliza el nodo webresponse.

Buenas prácticas

Asigna siempre una política a los webhooks que reciben tráfico externo real.
Usa la URL DEV durante el desarrollo y pruebas para no contaminar las estadísticas de producción.
Revisa el log de accesos regularmente para detectar IPs sospechosas y ajustar las listas de filtrado.
Activa HMAC cuando el servicio externo lo soporte (Stripe, GitHub, Shopify) — es la capa de seguridad más robusta.
Combina rate limiting + IP whitelist para APIs internas de alto riesgo.

Ver también

Bloquear un recurso con clave