# React to events

Webhooks or polling. Runs in your test sandbox: nothing is issued, every pass is a test preview. Authenticate with `Authorization: Bearer $PASSBOOK_KEY`. Ids in the examples are placeholders: use the ids your sandbox returns.

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.

```json
{ "eventTypes": ["pass.issued", "pass.updated", "pass.voided"] }
```

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.

```json
{ "type": "pass.issued" }
```

The answer carries `captureId`: the stored request.

## Read it in the tester

Open the [webhook tester](https://passbook.mobile/developers/webhooks). 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**

```ts
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](https://passbook.mobile/developers/reference/webhook-endpoints#captures-replay) 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**

```ts
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

- [POST /api/v1/webhook-endpoints/capture](https://passbook.mobile/developers/reference/webhook-endpoints#ensureCapture): Get the sandbox's capture endpoint, making it if it has none (`pb.webhookEndpoints.ensureCapture`)
- [POST /api/v1/webhook-endpoints/{id}/test](https://passbook.mobile/developers/reference/webhook-endpoints#sendTest): Send a test event to this endpoint (`pb.webhookEndpoints.sendTest`)
- [POST /api/v1/webhook-endpoints/{id}/captures/{captureId}/replay](https://passbook.mobile/developers/reference/webhook-endpoints#captures-replay): Sign a stored request again and store it as a new capture (`pb.webhookEndpoints.captures.replay`)
- [GET /api/v1/events](https://passbook.mobile/developers/reference/events#list): Event feed (`pb.events.list`)

More guides: https://passbook.mobile/developers/guides
