Suscripciones de webhook

Una suscripción es un endpoint HTTPS tuyo más la lista de eventos que quieres recibir en él.

Todos los endpoints de esta página requieren que la función de webhooks esté habilitada en tu cuenta; de lo contrario devuelven 403 FEATURE_DISABLED.

Límites

Máximo 5 suscripciones activas por cuenta. Las inactivas no cuentan.
Una sola suscripción activa por URL.
El secreto de firma se muestra una única vez, al crearla.

El objeto suscripción

string

Identificador (UUID) de la suscripción.

string

Endpoint HTTPS que recibe los eventos.

array

Eventos a los que está suscrita.

boolean

Si está recibiendo eventos.

string

RFC 3339.

string

RFC 3339.

string

Secreto de firma. Solo aparece en la respuesta de creación.

Crear una suscripción

POST /v1/webhook-subscriptions

string

required

Endpoint que recibirá los eventos. Debe ser https y públicamente accesible.

array

required

Lista no vacía de eventos. Consulta el catálogo.

Devuelve 201 Created con la suscripción y el secreto de firma.

curl -X POST "https://api.alaramx.com/v1/webhook-subscriptions" \
  -H "Authorization: Bearer $ALARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.mi-negocio.com/webhooks/alara",
    "event_types": ["pass.created", "pass.balanceUpdate", "scan.created"]
  }'

{
  "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "url": "https://api.mi-negocio.com/webhooks/alara",
  "event_types": ["pass.created", "pass.balanceUpdate", "scan.created"],
  "active": true,
  "created_at": "2026-07-24T17:00:00Z",
  "updated_at": "2026-07-24T17:00:00Z",
  "secret": "9f2c4d6e8a0b2c4d6e8a0b2c4d6e8a0b2c4d6e8a0b2c4d6e8a0b2c4d6e8a0b2c"
}

Guarda el secret en ese momento. No vuelve a aparecer en ninguna respuesta y no existe endpoint de rotación. Si lo pierdes, elimina la suscripción y crea una nueva.

URLs rechazadas

Por seguridad, Alara rechaza con 400 INVALID_WEBHOOK_URL:

Cualquier esquema que no sea https.
localhost y dominios terminados en .internal.
Direcciones IP de bucle local, privadas o de enlace local.

Errores

HTTP	`code`	Causa
`400`	`INVALID_WEBHOOK_URL`	La URL no cumple los requisitos anteriores.
`400`	`INVALID_WEBHOOK_EVENT_TYPE`	Un evento no existe, o la lista viene vacía.
`409`	`WEBHOOK_SUBSCRIPTION_LIMIT_REACHED`	Ya tienes 5 suscripciones activas.
`409`	`WEBHOOK_SUBSCRIPTION_DUPLICATE_URL`	Ya existe una suscripción activa con esa URL.
`403`	`FEATURE_DISABLED`	La función no está habilitada.

Listar suscripciones

GET /v1/webhook-subscriptions

Devuelve 200 OK con un objeto { "subscriptions": [ ... ] }. Nunca incluye el secreto.

curl "https://api.alaramx.com/v1/webhook-subscriptions" \
  -H "Authorization: Bearer $ALARA_API_KEY"

Consultar una suscripción

GET /v1/webhook-subscriptions/{id}

string

required

UUID de la suscripción.

Devuelve 200 OK con la suscripción, o 404 WEBHOOK_SUBSCRIPTION_NOT_FOUND.

Actualizar una suscripción

PATCH /v1/webhook-subscriptions/{id}

Actualización parcial: lo que no envíes no cambia.

string

Nuevo endpoint. Si lo omites, no cambia.

array

Nueva lista de eventos, reemplaza la anterior. Una lista vacía o ausente deja la suscripción sin cambios.

boolean

Activa o pausa la suscripción. Si lo omites, no cambia.

Devuelve 200 OK con la suscripción actualizada.

curl -X PATCH "https://api.alaramx.com/v1/webhook-subscriptions/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" \
  -H "Authorization: Bearer $ALARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

curl -X PATCH "https://api.alaramx.com/v1/webhook-subscriptions/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" \
  -H "Authorization: Bearer $ALARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "event_types": ["scan.created"] }'

Al desactivar una suscripción, las entregas que ya estaban en cola para ella se descartan; no quedan en pausa a la espera de reactivarla. Vuelve a activarla solo cuando tu endpoint esté listo.

No puedes vaciar la lista de eventos con PATCH. Para dejar de recibir todo, desactiva o elimina la suscripción.

Eliminar una suscripción

DELETE /v1/webhook-subscriptions/{id}

Devuelve 204 No Content.

curl -X DELETE "https://api.alaramx.com/v1/webhook-subscriptions/a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d" \
  -H "Authorization: Bearer $ALARA_API_KEY"

Rotar el secreto

No existe un endpoint de rotación. Para cambiar el secreto de un endpoint:

Crea una suscripción nueva

Apunta a una ruta distinta de tu servidor, por ejemplo /webhooks/alara-v2, y guarda el secreto nuevo.

Verifica que recibe eventos

Confirma que la ruta nueva procesa y valida correctamente.

Elimina la anterior

Borra la suscripción vieja cuando dejes de recibir tráfico en ella.

Si mantienes las dos activas un rato, recibirás cada evento por ambas rutas. Como el id del evento es el mismo en las dos entregas, tu lógica de idempotencia evitará procesarlo dos veces.

Empezar

Referencia

Webhooks

Suscripciones

Suscripciones de webhook

Límites

El objeto suscripción

Crear una suscripción

URLs rechazadas

Errores

Listar suscripciones

Consultar una suscripción

Actualizar una suscripción

Eliminar una suscripción

Rotar el secreto

​Suscripciones de webhook

​Límites

​El objeto suscripción

​Crear una suscripción

​URLs rechazadas

​Errores

​Listar suscripciones

​Consultar una suscripción

​Actualizar una suscripción

​Eliminar una suscripción

​Rotar el secreto

Suscripciones de webhook

Límites

El objeto suscripción

Crear una suscripción

URLs rechazadas

Errores

Listar suscripciones

Consultar una suscripción

Actualizar una suscripción

Eliminar una suscripción

Rotar el secreto