Webhooks
Ejecución de pruebas, logging, configuración asistida por IA y analiticas de webhooks.
Webhooks
¿Para qué sirve?
- Exponer eventos internos (alarmas, tareas, extracciones) a sistemas externos sin que ellos tengan que hacer polling.
- Garantizar entrega con reintentos automáticos y firma HMAC en cada request.
- Configurar un webhook sin escribir código gracias al asistente de IA.
¿Cómo funciona?
Cada evento interno dispara un POST a la URL registrada con un payload canónico y una firma X-Signature HMAC-SHA256. Si el destino devuelve 5xx o 4xx, Rela reintenta con backoff exponencial hasta 6 veces. Cada intento queda registrado en el log de entregas para debugging.
Ejecución de Pruebas
Antes de activar un webhook en producción, puedes ejecutar una prueba manual para verificar que el endpoint destino responde correctamente:
POST /api/v1/integrations/webhooks/{webhook_id}/test
{
"sample_payload": { "event": "task.created", "task_id": "test_123" }
}La prueba envia el payload al endpoint configurado y retorna el resultado:
| Campo | Descripción |
|---|---|
status_code | Codigo HTTP de respuesta del destino |
response_body | Cuerpo de la respuesta (truncado a 1 KB) |
latency_ms | Tiempo de respuesta en milisegundos |
success | true si el status esta entre 200-299 |
Logging de Entregas
Cada entrega de webhook se registra con información detallada para depuracion:
| Campo | Tipo | Descripción |
|---|---|---|
delivery_id | string | Identificador único de la entrega |
webhook_id | string | Webhook que origino la entrega |
event_type | string | Tipo de evento disparador |
payload | object | Payload enviado |
status_code | int | Codigo de respuesta HTTP |
attempt | int | Numero de intento (1-5) |
latency_ms | int | Latencia de la entrega |
created_at | datetime | Momento de la entrega |
Los logs se conservan por 30 dias y se consultan via:
GET /api/v1/integrations/webhooks/{webhook_id}/deliveries?limit=50&skip=0Reintentos Automaticos
Cuándo una entrega falla (status >= 400 o timeout), el sistema reintenta automáticamente:
| Intento | Delay |
|---|---|
| 1 | Inmediato |
| 2 | 30 segundos |
| 3 | 5 minutos |
| 4 | 30 minutos |
| 5 | 2 horas |
Despues del quinto intento fallido, el webhook se marca como failing y se
notifica al administrador. No se desactiva automáticamente.
Configuración Asistida por IA
El asistente de IA puede sugerir configuraciones de webhook basandose en la descripción del caso de uso:
POST /api/v1/integrations/webhooks/ai-config
{
"description": "Notificar a Slack cuando se complete una tarea critica"
}El sistema analiza la descripción y sugiere:
- Eventos a suscribir
- Filtros recomendados
- Formato del payload
- Headers de autenticación
El usuario revisa y aprueba la configuración antes de activarla.
Analiticas de Webhooks
El dashboard de analiticas muestra metricas agregadas por webhook:
- Tasa de exito — Porcentaje de entregas exitosas (ultimos 7 dias)
- Latencia promedio — Tiempo medio de respuesta del destino
- Entregas por dia — Volumen de entregas en el periodo
- Errores frecuentes — Top 5 codigos de error recibidos
Las metricas se consultan via GET /api/v1/integrations/webhooks/{webhook_id}/analytics.
Beneficios clave
- Entrega garantizada con reintentos automáticos y backoff exponencial.
- Firma HMAC-SHA256 para que el receptor valide autenticidad.
- Log de entregas con cuerpo + respuesta para cada intento.
- Asistente de IA para configurar la URL y los eventos sin JSON manual.
- Mismo motor para webhooks internos (Rela → destino) y salientes a terceros.