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 responde2xx, 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.
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: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:Si tu servidor estuvo caído más de 34 horas, esos eventos se perdieron
Si tu servidor estuvo caído más de 34 horas, esos eventos se perdieron
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.Si necesitas saber si un evento se envió, escríbenos
Si necesitas saber si un evento se envió, escríbenos
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
El estado que recibes es el del momento de la entrega
El estado que recibes es el del momento de la entrega
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.
Un reintento trae el estado actualizado
Un reintento trae el estado actualizado
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.
Los escaneos rechazados también se entregan
Los escaneos rechazados también se entregan
Un
scan.created no significa que se haya concedido el acceso. Revisa siempre data.status.
