Skip to main content

Entregas y reintentos

Conocer las reglas de entrega te ayuda a diseñar un receptor que no pierda eventos ni los procese dos veces.

Cómo es la entrega

Alara ignora por completo el cuerpo de tu respuesta. Solo importa el código de estado. No necesitas devolver nada.

Latencia

Los webhooks se entregan de forma asíncrona: la operación original (crear un pase, registrar un escaneo) responde sin esperar a tu servidor. En condiciones normales, un evento llega a tu endpoint entre 5 y 35 segundos después del hecho que lo originó. No diseñes flujos que dependan de recibirlo al instante.

Reintentos

Si tu servidor no responde 2xx, Alara reintenta hasta 7 veces en total (el intento original más 6 reintentos), con este calendario: Después del séptimo intento fallido, la entrega se marca como fallida definitivamente y no se vuelve a intentar.
El calendario de reintentos es el mismo para todos los fallos. Un 400 de tu endpoint se reintenta igual que un 503: si vas a rechazar un evento a propósito, respóndele 2xx para que Alara no lo reintente durante 34 horas.

Entregas independientes por endpoint

Cada suscripción recibe su propia entrega del mismo evento, y cada una reintenta por separado. Si tienes dos endpoints y uno está caído, el otro sigue recibiendo con normalidad: la falla de uno nunca provoca reenvíos al otro.

Entregas descartadas

Algunas entregas pendientes se descartan sin reintentarse:
Desactivar una suscripción no pausa sus entregas: las descarta. Si vas a hacer mantenimiento en tu endpoint, es preferible dejarlo activo y devolver un 503, para que Alara reintente cuando vuelvas.

No hay reenvío manual

Alara no ofrece por el momento un historial de entregas consultable ni un botón para reenviar un evento. Esto tiene dos consecuencias prácticas:
Reconcilia consultando la API: GET /v1/passes y GET /v1/scans aceptan filtros created_from y updated_from para recuperar exactamente lo ocurrido durante la caída.
El equipo de dev@alaramx.com puede revisar el estado de las entregas. Ten a la mano el Alara-Webhook-Id, o bien el pase y la fecha aproximada.

Cómo construir un receptor robusto

1

Verifica la firma

Antes que nada. Consulta Verificar firmas.
2

Descarta duplicados por `Alara-Webhook-Id`

Guarda los identificadores ya procesados. Si el evento ya se procesó, responde 200 y termina.
3

Encola y responde de inmediato

Persiste el evento en tu cola o base de datos y devuelve 2xx sin esperar. Nunca hagas trabajo pesado, ni llames a otras APIs, dentro de la petición del webhook: excederás los 10 segundos.
4

Procesa fuera de la petición

Un worker toma el evento de la cola y lo procesa con sus propios reintentos, ya independiente de Alara.
5

Monitorea

Alerta si dejas de recibir eventos durante un periodo inusual: puede indicar que tu endpoint está devolviendo errores y agotando reintentos.
Ejemplo con Express

Cambios de estado poco intuitivos

La carga útil es una fotografía tomada al enviarse, no al ocurrir el hecho. Si un pase cambió dos veces muy rápido, las dos entregas pueden mostrar el mismo estado final.Para saber qué cambió, compara contra el estado que tengas guardado.
Si el primer intento falló y el pase cambió mientras tanto, el reintento entregará el estado nuevo, no el que existía en el momento original.
Un scan.created no significa que se haya concedido el acceso. Revisa siempre data.status.