React to events

Webhooks or polling

Markdown

Hear about passes as they change, by webhook or by polling. In a sandbox the webhook goes to a capture endpoint: PassBook stores the signed request instead of sending it, so you read, verify and replay the exact bytes a real endpoint would get. There is no public URL to call.

Get the capture endpoint

It exists once per sandbox. The first call returns its signing secret; later calls return secret: null, so save it.

{ "eventTypes": ["pass.issued", "pass.updated", "pass.voided"] }
Open in consoleOpens the console with this request filled in.

Store the secret as PASSBOOK_WEBHOOK_SECRET.

Send a test event

type is any event type; every one but webhook.test carries sample data. Paste the endpoint id into the path.

{ "type": "pass.issued" }
Open in consoleOpens the console with this request filled in.

The answer carries captureId: the stored request.

Read it in the tester

Open the webhook tester. The capture is listed with its headers, raw body and attempt log. The verify panel checks the signature in the page and names the usual mistakes: a re-serialized body, a millisecond timestamp, a rotated secret.

Verify in your handler

Verify the raw body before you parse it. Parsing first changes the bytes and the check fails.

Verify a webhook
import { verifyWebhook } from '@passbook/sdk';/** A fetch-style handler: Workers, Deno, Bun, or Node behind a Request adapter. */export async function handle(request: Request): Promise<Response> {  // Verify the raw body. Parsing it first changes the bytes.  const body = await request.text();  try {    const event = await verifyWebhook(      body,      request.headers,      process.env.PASSBOOK_WEBHOOK_SECRET ?? '',    );    if (event.type === 'pass.issued') console.log('issued', event.pass.id);    return new Response('ok');  } catch {    return new Response('bad signature', { status: 400 });  }}

Reject a timestamp more than 5 minutes off. Dedupe on the event id: a delivery can arrive more than once. Answer 2xx fast and do the work after.

Replay a capture

Replay it with the endpoint id and the captureId, or use Replay in the tester. The same event arrives again, so your handler must dedupe.

Or poll

The feed carries the same events, oldest first. Keep the cursor from each page, even an empty one.

Read events as they happen
import { PassBook } from '@passbook/sdk';const pb = new PassBook({ apiKey: process.env.PASSBOOK_KEY ?? '' });let cursor: string | undefined;for (let i = 0; i < 3; i++) {  const page = await pb.events.list({ after: cursor, limit: 100 });  for (const event of page.items) console.log(event.type, event.id);  // Keep the cursor, even when the page is empty: the next call starts there.  cursor = page.nextCursor ?? cursor;  await new Promise((resolve) => setTimeout(resolve, 2000));}

Result

The capture list shows each event with a verified signature and its replays. In your code, a forged request answers 400 and a verified one logs the event.

Operations