Catálogo de eventos

Estos son los tipos de evento que puedes incluir en event_types al crear una suscripción.

Evento	Se dispara cuando
`pass.created`	Se emite un pase.
`pass.updated`	Cambian los campos visibles de un pase.
`pass.deleted`	Un pase se desactiva o expira.
`pass.balanceUpdate`	Cambia el saldo de lealtad de un pase.
`pass.stamp_card_updated`	Cambia el estado de una tarjeta de sellos.
`scan.created`	Se registra un escaneo.

Fíjate en que pass.balanceUpdate usa mayúscula intercalada, mientras que el resto usa guion bajo. Cópialos tal cual.

Carga útil de los eventos de pase

Los cinco eventos pass.* comparten la misma forma de data:

string

El pass_id del pase.

string

Plantilla con la que se emitió.

string

creating, creation_failed, issued, active, removed o deactivated.

object

Campos visibles del pase. Nota que la llave es visible, no visible_data.

integer

Saldo o número de sellos. Ausente en pases sin programa de lealtad.

string

Creación del pase, RFC 3339.

string

Última modificación del pase, RFC 3339.

La carga útil no incluye los datos ocultos (hidden), el qr_value ni el download_url. Si los necesitas, consulta GET /v1/passes/{id} al recibir el evento.

`pass.created`

Se emite un pase nuevo. Como la emisión es asíncrona, el status de la carga útil suele ser creating o issued. Si necesitas el download_url, consulta el pase al recibir este evento.

{
  "id": "0f9c1a3e-5d02-4b17-9c3b-a1d2e3f40506",
  "type": "pass.created",
  "created_at": "2026-07-24T09:14:22.481Z",
  "data": {
    "id": "cliente-001",
    "template_id": "lealtad_oro",
    "status": "creating",
    "visible": {
      "nombre": "Ada Lovelace",
      "miembro_desde": "2026-07-24",
      "puntos": "0"
    },
    "balance": 0,
    "created_at": "2026-07-24T09:14:22.402Z",
    "updated_at": "2026-07-24T09:14:22.402Z"
  }
}

`pass.updated`

Cambian los campos visibles de un pase. Ocurre al actualizarlo por API, al restaurarlo o reactivarlo, y cuando una regla de activación escribe un campo.

Una actualización que toca solo datos ocultos (hidden) no genera este evento. Solo los cambios en visible lo disparan.

{
  "id": "3a77b1c8-9e40-4f2a-b6d1-77c0e9a2b311",
  "type": "pass.updated",
  "created_at": "2026-07-24T11:02:07.115Z",
  "data": {
    "id": "cliente-001",
    "template_id": "lealtad_oro",
    "status": "active",
    "visible": {
      "nombre": "Ada Lovelace",
      "nivel": "Oro"
    },
    "balance": 42,
    "created_at": "2026-07-01T08:30:00.000Z",
    "updated_at": "2026-07-24T11:02:06.981Z"
  }
}

`pass.deleted`

Un pase se desactiva, se elimina o expira automáticamente.

{
  "id": "c41d0e6b-2a8f-4d90-8e3c-5b6a7c8d9e01",
  "type": "pass.deleted",
  "created_at": "2026-07-24T00:05:11.006Z",
  "data": {
    "id": "cliente-001",
    "template_id": "lealtad_oro",
    "status": "deactivated",
    "visible": {
      "nombre": "Ada Lovelace",
      "puntos": "42"
    },
    "balance": 42,
    "created_at": "2026-07-01T08:30:00.000Z",
    "updated_at": "2026-07-24T00:05:10.884Z"
  }
}

`pass.balanceUpdate`

Cambia el saldo de lealtad de un pase, ya sea por POST /v1/passes/{id}/loyalty o por una regla de activación. El campo balance trae el valor posterior al cambio; el evento no incluye el delta aplicado.

{
  "id": "9d2e5f01-77aa-4c3b-9012-3456789abcde",
  "type": "pass.balanceUpdate",
  "created_at": "2026-07-24T14:41:59.220Z",
  "data": {
    "id": "cliente-001",
    "template_id": "lealtad_oro",
    "status": "active",
    "visible": {
      "nombre": "Ada Lovelace",
      "puntos": "47"
    },
    "balance": 47,
    "created_at": "2026-07-01T08:30:00.000Z",
    "updated_at": "2026-07-24T14:41:59.118Z"
  }
}

`pass.stamp_card_updated`

Cambia el estado de una tarjeta de sellos: el contador avanza y, con él, la imagen que ve el portador. En este evento, balance es el número de sellos acumulados.

{
  "id": "5b8c9d0e-1f23-4456-a789-bcdef0123456",
  "type": "pass.stamp_card_updated",
  "created_at": "2026-07-24T14:42:00.004Z",
  "data": {
    "id": "cliente-001",
    "template_id": "sellos_cafe",
    "status": "active",
    "visible": {
      "nombre": "Ada Lovelace",
      "sellos": "7"
    },
    "balance": 7,
    "created_at": "2026-07-01T08:30:00.000Z",
    "updated_at": "2026-07-24T14:41:59.993Z"
  }
}

Un cambio de saldo en una tarjeta de sellos puede generar tanto pass.balanceUpdate como pass.stamp_card_updated. Suscríbete solo al que necesites para no duplicar trabajo.

`scan.created`

Se registra un escaneo.

Carga útil

string

Identificador del escaneo.

string

Lector donde se registró.

string

Nombre del lector. Ausente si el lector no tiene nombre registrado.

string

Pase escaneado.

string

Momento del escaneo, con formato 2026-07-24 14:41:58.842 +0000 UTC.

object

Metadatos enviados al registrar el escaneo.

string

Veredicto: succeeded o failed.

string

Motivo del rechazo cuando status es failed. Cadena vacía si fue exitoso.

El created_at dentro de data usa el formato con espacios, para coincidir exactamente con GET /v1/scans. El created_at de la envoltura sí es RFC 3339. Son dos formatos distintos en el mismo mensaje.

Los escaneos rechazados también se entregan. Revisa status antes de reaccionar: un scan.created no significa que el acceso se haya concedido.

{
  "id": "e1f2a3b4-c5d6-4789-9012-3456789abcde",
  "type": "scan.created",
  "created_at": "2026-07-24T14:41:58.900Z",
  "data": {
    "id": "7c1f9a20-4b3d-4e5f-8a90-1b2c3d4e5f60",
    "scanner_id": "sucursal-centro-01",
    "scanner_name": "Sucursal Centro",
    "pass_id": "cliente-001",
    "created_at": "2026-07-24 14:41:58.842 +0000 UTC",
    "metadata": {
      "ticket": "A-4471"
    },
    "status": "succeeded",
    "reason": ""
  }
}

{
  "id": "a0b1c2d3-e4f5-4678-89ab-cdef01234567",
  "type": "scan.created",
  "created_at": "2026-07-24T14:52:03.771Z",
  "data": {
    "id": "9e8d7c6b-5a49-4382-9170-6f5e4d3c2b1a",
    "scanner_id": "sucursal-centro-01",
    "pass_id": "cliente-001",
    "created_at": "2026-07-24 14:52:03.688 +0000 UTC",
    "metadata": {},
    "status": "failed",
    "reason": "DOUBLE_SCAN"
  }
}

Elegir a qué suscribirte

Sincronizar tu CRM

pass.created, pass.updated y pass.deleted.

Contabilizar visitas

scan.created, filtrando por status: "succeeded".

Seguir la lealtad

pass.balanceUpdate, o pass.stamp_card_updated para tarjetas de sellos.

Detectar bajas

pass.deleted, y pass.updated con status: "removed".

Suscríbete solo a lo que vas a procesar. Cada evento extra es tráfico y trabajo adicional en tu servidor sin beneficio.

Empezar

Referencia

Webhooks

Catálogo de eventos

Catálogo de eventos

Carga útil de los eventos de pase

`pass.created`

`pass.updated`

`pass.deleted`

`pass.balanceUpdate`

`pass.stamp_card_updated`

`scan.created`

Carga útil

Elegir a qué suscribirte

Sincronizar tu CRM

Contabilizar visitas

Seguir la lealtad

Detectar bajas

​Catálogo de eventos

​Carga útil de los eventos de pase

​pass.created

​pass.updated

​pass.deleted

​pass.balanceUpdate

​pass.stamp_card_updated

​scan.created

​Carga útil

​Elegir a qué suscribirte

Sincronizar tu CRM

Contabilizar visitas

Seguir la lealtad

Detectar bajas

Catálogo de eventos

Carga útil de los eventos de pase

`pass.created`

`pass.updated`

`pass.deleted`

`pass.balanceUpdate`

`pass.stamp_card_updated`

`scan.created`

Carga útil

Elegir a qué suscribirte