Skip to main content

​
Webhooks

En lugar de consultar la API cada cierto tiempo para saber si algo cambió, registra un endpoint HTTPS y Alara te avisa: cuando se emite un pase, cuando cambia un saldo, cuando se registra un escaneo.
Esta función debe estar habilitada en tu cuenta. Si al crear una suscripción recibes 403 FEATURE_DISABLED, escríbenos a dev@alaramx.com.

​
Cómo funciona

1

Registras tu endpoint

Creas una suscripción indicando tu URL HTTPS y qué eventos quieres recibir. Alara te devuelve un secreto de firma, una sola vez.
2

Alara te envía los eventos

Cada evento llega como un POST con cuerpo JSON y encabezados de firma.
3

Verificas la firma

Compruebas que el mensaje viene realmente de Alara antes de procesarlo.
4

Respondes rápido

Devuelves 2xx de inmediato y procesas el evento en segundo plano.

​
Guías

Suscripciones

Registra, edita y elimina tus endpoints.

Eventos

Catálogo completo con ejemplos de cada carga útil.

Verificar firmas

Valida que el evento viene de Alara.

Entregas y reintentos

Qué pasa si tu servidor falla o está caído.

​
Formato del evento

Todos los eventos comparten la misma envoltura:
​
string
Identificador único del evento. Se mantiene idéntico en todos los reintentos: úsalo para descartar duplicados.
​
string
Tipo de evento, por ejemplo pass.created. Consulta el catálogo.
​
string
Momento en que se generó el evento, RFC 3339.
​
object
Estado del recurso afectado. Su forma depende del type.

​
Requisitos de tu endpoint

Alara rechaza URLs que no sean https, así como localhost, dominios internos y direcciones IP privadas o de bucle local.Para probar en tu máquina, usa un túnel que exponga tu servidor local con una URL pública HTTPS.
Cualquier código entre 200 y 299 cuenta como éxito. El tiempo límite es de 10 segundos por intento, contando conexión y respuesta.Haz lo mínimo indispensable: valida la firma, encola el evento y responde. No proceses de forma síncrona.
La entrega es al menos una vez. Un mismo evento puede llegar más de una vez, por ejemplo si tu respuesta se perdió en la red. Usa el campo id como llave de idempotencia.
Los eventos pueden llegar desordenados, sobre todo cuando hubo reintentos. No supongas que pass.created llegará antes que un pass.updated del mismo pase.

​
Datos que se incluyen

Las cargas útiles llevan solo lo necesario para reaccionar al cambio: identificadores, campos visibles, estado y saldo.
Los eventos nunca incluyen los datos ocultos (hidden) del pase, el qr_value ni el download_url. Si necesitas esa información, consulta el pase con GET /v1/passes/{id} al recibir el evento.
Además, data es una fotografía del estado al momento de la entrega, no un diff. Si el recurso cambió dos veces muy rápido, ambas entregas pueden mostrar el mismo estado final. Para saber qué cambió, compara con lo que tengas guardado.