Webhooks

Webhooks push pass lifecycle events to your systems the moment they happen, so you never need to poll. Manage them on the Webhooks page (endpoint management is owner-only; members can inspect deliveries) or via the webhooks API.

Events

Event	Fired when
`pass.issued`	A pass finished issuing and is live
`pass.updated`	Pass data or template version changed
`pass.voided`	A pass was voided, manually or automatically by a scan-limit rule
`pass.failed`	Issuance failed
`pass.scanned`	A scan was recorded. Every decision fires (accepted and denied). The event fires at server receipt, so an offline or date-overridden scan can arrive at a different real time than its operational `scannedAt`
`webhook.test`	You clicked Send test on an endpoint. Not subscribable: it goes only to the endpoint you tested

Delivery payload

Every delivery is a JSON POST with the same envelope:

{
  "id": "0b6cbe0f-8ac9-4b3e-9d2e-6f0f4d5f2a11",
  "type": "pass.updated",
  "timestamp": "2026-07-29T09:30:00.000Z",
  "correlationId": "019fcbd8-7e4a-71cc-a560-c92c018188b8",
  "data": {}
}

id: unique delivery ID. Use it to deduplicate (see Idempotency).
type: the event type from the table above.
timestamp: when the delivery was created (ISO 8601).
correlationId: ties the delivery to the API request or job that caused it, null when there was no correlated caller. Quote it in support requests.
data: the event’s subject.

What `data` contains

One rule across every event: data is the event’s subject, in the same shape the REST API uses for that resource, carrying only state the event establishes.

data.id is always the thing the event is about: the pass for a lifecycle event, the scan for a scan event.
State the event merely observed is deliberately absent. Deliveries are retried, and an offline scan report can sync hours after its operational scan time, so a pass label or a scan counter would arrive stale while looking authoritative. Fetch what you need, or cache it from the event that set it, keyed by externalPassId.

Every sample body below is generated from the same schemas the API validates deliveries against, so what you see is what your endpoint receives. The examples follow one membership pass: issued, updated, scanned, and finally voided.

`pass.issued`

Field	Description
`id`	Passlet pass ID
`externalPassId`	The pass ID in your source system
`status`	`ISSUED`
`hostedLinks`	`smart`, `apple`, and `google` hosted link URLs, `null` when unavailable

{
  "id": "4b1c8f0e-6a2d-4c19-9f83-1d5e7a2b6c04",
  "type": "pass.issued",
  "timestamp": "2026-08-04T08:02:11.418Z",
  "correlationId": "019fcbd8-6f11-7a03-9c42-3b8e1d0a5f27",
  "data": {
    "id": "019fb76a-3358-7cd7-b9c2-b7f61bd0dbba",
    "externalPassId": "member-8421",
    "status": "ISSUED",
    "hostedLinks": {
      "apple": "https://passes.passlet.io/a/AZ-3aj5RfECaEVLQyLfiqg1iIiK0xiJ3xT2E1aO4qqhw",
      "google": "https://passes.passlet.io/g/AZ-3ak9ifVGLImPh2cjzuwzJuSrPjE_FV2-akpbtiWIQ",
      "smart": "https://passes.passlet.io/s/AZ-3amXtblKDrIvfE6DrPQqOjDMBcGSp1EA7CQmvCfNw"
    }
  }
}

`pass.updated`

Field	Description
`id`	Passlet pass ID
`externalPassId`	The pass ID in your source system
`status`	Pass status after the update
`templateVersionId`	Template version the pass now renders with
`changedFields`	Pass fields the update touched, see below
`hostedLinks`	`smart`, `apple`, and `google` hosted link URLs, `null` when unavailable

{
  "id": "7d90a2c4-1e63-4b58-8c07-9f2a4d6b3e11",
  "type": "pass.updated",
  "timestamp": "2026-08-04T08:07:45.902Z",
  "correlationId": "019fcbd8-7002-7bd6-8e19-64c3f7a29b80",
  "data": {
    "id": "019fb76a-3358-7cd7-b9c2-b7f61bd0dbba",
    "externalPassId": "member-8421",
    "status": "ISSUED",
    "templateVersionId": "a3f1c0d2-9b47-4e15-8a6d-2c7e5f0b91d4",
    "changedFields": [
      "variables",
      "redemption",
      "expiresAt"
    ],
    "hostedLinks": {
      "apple": "https://passes.passlet.io/a/AZ-3aj5RfECaEVLQyLfiqg1iIiK0xiJ3xT2E1aO4qqhw",
      "google": "https://passes.passlet.io/g/AZ-3ak9ifVGLImPh2cjzuwzJuSrPjE_FV2-akpbtiWIQ",
      "smart": "https://passes.passlet.io/s/AZ-3amXtblKDrIvfE6DrPQqOjDMBcGSp1EA7CQmvCfNw"
    }
  }
}

`changedFields` semantics

changedFields lists the top-level pass fields the update touched. It is not a value-level diff:

A variable change is reported as variables. Individual variable names are never listed; to find out which variable changed, fetch the pass (GET /v1/passes/{id}) and compare with your source system.
redemption and expiresAt are always included whenever the update contained variables, because variables can drive the resolved redemption policy and expiry. Their presence does not guarantee those values actually changed.
A template upgrade reports templateVersionId (together with variables, redemption, and expiresAt). Data updates do not, so this entry is the way to tell upgrades and data updates apart.
An update that writes identical values still fires the event, with the same changedFields.
Treat unknown entries as possible and ignore ones you do not recognise. For example, manual_requeue appears when an operator requeues an update job from the console.

`pass.voided`

Field	Description
`id`	Passlet pass ID
`externalPassId`	The pass ID in your source system
`status`	`VOID`, or `EXPIRED` when the pass passed its expiry
`reason`	Why it was voided; `"unspecified"` when no reason was given

{
  "id": "c5e70b39-8d4a-4f22-b1c6-0a93e8d7f254",
  "type": "pass.voided",
  "timestamp": "2026-08-04T09:12:07.556Z",
  "correlationId": "019fcbd9-1a58-7c94-b0f3-27d6e4a1c9b5",
  "data": {
    "id": "019fb76a-3358-7cd7-b9c2-b7f61bd0dbba",
    "externalPassId": "member-8421",
    "status": "VOID",
    "reason": "membership cancelled by the holder"
  }
}

`pass.failed`

Field	Description
`id`	Passlet pass ID
`externalPassId`	The pass ID in your source system
`status`	`FAILED`
`error`	Failure message, with credential-shaped substrings redacted

{
  "id": "f2a6d81b-30c7-4e95-a4d2-6b1f9c0e7538",
  "type": "pass.failed",
  "timestamp": "2026-08-04T08:03:52.107Z",
  "correlationId": "019fcbd8-6f4c-7e21-9a08-51b7d2c6e390",
  "data": {
    "id": "019fb76a-4c81-7de3-a5f0-3c92b7e14a68",
    "externalPassId": "member-8422",
    "status": "FAILED",
    "error": "Apple Wallet rejected the pass: barcode message exceeds the supported length"
  }
}

`pass.scanned`

The scan event carries the Scan object as data, byte for byte what GET /v1/scans/{id} returns. One parser handles the API and the webhook:

{
  "id": "8e14b7f2-5c39-4a06-9d8b-2f70a3c5e619",
  "type": "pass.scanned",
  "timestamp": "2026-08-04T08:16:30.835Z",
  "correlationId": "019fcbd8-7e33-7a41-bb2f-2f0f4d5f2a11",
  "data": {
    "id": "019fcbd8-7e4a-71cc-a560-c92c018188b8",
    "result": "accepted",
    "reason": "valid",
    "verified": "online",
    "passId": "019fb76a-3358-7cd7-b9c2-b7f61bd0dbba",
    "externalPassId": "member-8421",
    "projectId": "6c2d94f7-01a8-4be3-95d7-8f34e60b1a29",
    "scannedAt": "2026-08-04T08:16:30.764Z",
    "recordedAt": "2026-08-04T08:16:30.771Z",
    "deviceId": "dev_c71c1dccd18f5228",
    "metadata": {
      "note": "Main entrance"
    }
  }
}

Field	Description
`id`	Scan ID. Note this is the scan, not the delivery: the delivery ID is the envelope’s `id`
`result`	`accepted` or `denied`. The only field to branch on
`reason`	Machine-readable detail: `valid` for an acceptance, otherwise why it was denied
`verified`	`online` when the server decided in-band, `offline` when a device decided and reported later
`passId`	Passlet pass ID, `null` when nothing matched (`no_match`, `multiple_matches`)
`externalPassId`	The matched pass’s ID in your system, so you can key into your own records without a lookup
`projectId`	Project the scan was recorded under, `null` when unscoped
`scannedAt`	Effective operational scan time. A date override normalizes it into the selected fixed window
`recordedAt`	Real time the Passlet server received and stored the scan
`deviceId`	Enrolled Scanner device that recorded it, `null` for console and API scans
`metadata`	Context stored with the scan, see below

Per the rule above, the payload carries no pass label, status, or redemption counters: those are pass state the scan only observed. externalPassId is here so you never need them to route the event.

`metadata`

Whatever the scanning client attached (note, or any other key), plus two keys Passlet stamps itself:

conflict: present only on an offline-reported scan whose device verdict disagreed with what the server would have decided at report time. The value is the reason the server would have returned. The device’s verdict is what was acted on, so result and reason are never overwritten.
validateAsOf: the operator’s validity-date override (YYYY-MM-DD), when one was in force. It explains why the operational scannedAt date can differ from the real recordedAt date.

`webhook.test`

Sent only when you use Send test on an endpoint, so you can confirm your receiver verifies signatures and returns a 2xx before real traffic arrives. There is nothing to subscribe to, and it never reports pass or scan state: data names the endpoint you tested and nothing else.

Field	Description
`endpointId`	The endpoint the test was sent to

{
  "id": "d7c41e08-2b95-4a63-8107-9e5f3a2d6c48",
  "type": "webhook.test",
  "timestamp": "2026-08-04T07:58:03.221Z",
  "correlationId": "019fcbd8-6a0f-7b18-8e73-40c1d9f5a2e6",
  "data": {
    "endpointId": "2f8b1a47-c0d6-4e93-b512-7a6e04c8f3d1"
  }
}

Setting up an endpoint

On Webhooks, click Add webhook.
Enter your HTTPS endpoint URL and select the events to subscribe to.
Save. The signing secret is shown once; store it like a password, because you need it to verify deliveries.
Use Send test to queue a test event and confirm your endpoint responds.

Endpoints can be edited, disabled, enabled, and deleted at any time.

Verifying signatures

Every delivery is signed. The X-Passlet-Signature header has the form:

X-Passlet-Signature: t=1720000000,v1=5f8a...e3

t: unix timestamp (seconds) when the delivery was signed.
v1: hex HMAC-SHA256 of "{t}.{rawBody}" using your endpoint’s signing secret.

To verify:

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(rawBody: string, header: string, secret: string): boolean {
  const parts = Object.fromEntries(header.split(',').map((kv) => kv.split('=')));
  const timestamp = Number(parts.t);
  // Reject replays older than 5 minutes
  if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false;

  const expected = createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex');
  return timingSafeEqual(Buffer.from(parts.v1, 'hex'), Buffer.from(expected, 'hex'));
}

Compute the HMAC over the raw request body exactly as received, and parse the JSON only after verification. Reject deliveries with timestamps outside a 5 minute window in either direction.

Delivery tracking and retries

The Deliveries section records every attempt with its event type, status (PENDING, SUCCESS, FAILED), attempt count, and last response code or error. Failed deliveries are retried automatically with backoff; you can also redeliver a specific delivery manually (console or POST /v1/webhooks/deliveries/{id}/redeliver). Respond with a 2xx quickly and do the heavy processing asynchronously on your side. Non-2xx responses and timeouts count as failures.

Idempotency

Deliveries can arrive more than once (retries, redelivery). Use the delivery ID or the event’s entity state to make your handler idempotent.

Get started

Guides

Developers

Events

Delivery payload

What `data` contains

`pass.issued`

`pass.updated`

`changedFields` semantics

`pass.voided`

`pass.failed`

`pass.scanned`

`metadata`

`webhook.test`

Setting up an endpoint

Verifying signatures

Delivery tracking and retries

Idempotency

​Events

​Delivery payload

​What data contains

​pass.issued

​pass.updated

​changedFields semantics

​pass.voided

​pass.failed

​pass.scanned

​metadata

​webhook.test

​Setting up an endpoint

​Verifying signatures

​Delivery tracking and retries

​Idempotency

Events

Delivery payload

What `data` contains

`pass.issued`

`pass.updated`

`changedFields` semantics

`pass.voided`

`pass.failed`

`pass.scanned`

`metadata`

`webhook.test`

Setting up an endpoint

Verifying signatures

Delivery tracking and retries

Idempotency