Webhooks
Detalles
Buenas prácticas para una integración estable: evitar procesar dos veces, entender reintentos y ver el estado.
Fallos y buenas prácticas
Tres puntos evitan la mayoría de problemas en producción:
Responde 2xx cuando todo esté bien
HTTP 2xx significa que aceptaste la entrega; Alocis no programa nuevos intentos para ese hecho tras un 2xx. Responde 2xx solo después de validar el token y estar listo para procesar (o encolar) el evento.
Valida el token
Cada POST incluye el token de la cuenta en el campo token (prefijo whtok_). Compáralo con el valor del panel antes de dar acceso o disparar automatizaciones. Si falta o no coincide, responde con error (por ejemplo 401) y no ejecutes acciones sensibles.
Evita procesar dos veces
Cada entrega tiene un id único (whdlv_ en el JSON o cabecera X-Webhook-Id). Los reintentos automáticos repiten el mismo id y el mismo cuerpo grabado en el primer intento — usa ese id como clave de deduplicación.
Errores temporales (timeout, 408, 429, 5xx) se reenvían dentro de una ventana de 24 horas desde el primer intento, con hasta 8 intentos e intervalos de 1 min, 5 min, 15 min, 1 h, 4 h y 12 h. Otras respuestas 4xx son fallos definitivos. Ver la tabla abajo.
Idempotencia
Idempotencia significa que si llega la misma entrega otra vez, tu sistema no debe repetir el efecto (acceso duplicado, pedido duplicado, etc.).
- Usa el id de entrega (campo id en JSON o encabezado X-Webhook-Id, prefijo whdlv_) como clave.
- Los reintentos automáticos reutilizan el mismo id y el mismo contenido de negocio de la primera intento.
Reintentos y fallos
Los fallos temporales se reintentan dentro de una ventana de 24 horas desde el primer intento, con hasta 8 intentos e intervalos de 1 min, 5 min, 15 min, 1 h, 4 h y 12 h (el último usa el tiempo restante de la ventana).
| HTTP | Significado |
|---|---|
2xx | Entrega aceptada; no hay más intentos para este hecho. |
408, 429, 5xx | Error temporal — se programa otro intento dentro de la ventana. |
4xx (demais) | Error definitivo — la entrega se marca como fallida sin más intentos. |
| Timeout o conexión | Tratado como error temporal (misma política que 5xx). |
Los endpoints pausados o eliminados no reciben eventos nuevos; las entregas en curso siguen la política de reintento hasta aceptarse o agotar la ventana.
Estado en el panel
En Complementos → Webhook → Entregas ves si cada POST fue aceptado, falló o está en reintento, cuántos intentos hubo y un cuerpo redactado. Los destinos pausados no reciben eventos nuevos.
En nuevos intentos, Alocis reenvía el mismo snapshot guardado en el primer intento — el payload describe el estado en el momento del hecho, no el estado actual del recurso.