# Webhook endpoints

Webhooks and events · PassBook API reference. Authenticate with `Authorization: Bearer $PASSBOOK_KEY`.

## List webhook endpoints {#list}

`GET /api/v1/webhook-endpoints`

Lists the endpoints of this mode.

Scopes: `webhooks:manage`. SDK name: `pb.webhookEndpoints.list`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `cursor` | query | string · max 512 |  |  |

Returns `200`, a `WebhookEndpointPage`.

| Code | Status | Fix |
| --- | --- | --- |
| `CAPTURE_DEVELOPER_ONLY` |  | Make your sandbox in the developer portal and call this in Test mode. |
| `CAPTURE_NOT_STORED` |  | Send the request again. |
| `CAPTURE_TOO_LARGE` |  | Send a smaller body. |
| `CAPTURE_URL_FIXED` |  | Leave the url out, or create a URL endpoint instead. |
| `DELIVERY_PENDING` |  | Wait for it to send, then check GET /api/v1/webhook-endpoints/{id}/deliveries before replaying. |
| `EVENT_NOT_FOUND` |  | Check the id with GET /api/v1/scan/events. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_CURSOR` |  | Pass the nextCursor from the previous page unchanged, or drop it to start over. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_A_CAPTURE_ENDPOINT` |  | Use a capture endpoint: POST /api/v1/webhook-endpoints/capture returns your sandbox's. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `REPLAY_NOT_QUEUED` |  | Send the replay request again. |
| `REPLAY_TOO_LARGE` |  | Narrow the time range or replay in several smaller requests. |
| `RETENTION_RECEIPT_BUSY` |  | Wait a few seconds and send the request again. |
| `SAMPLE_EVENT_LIVE` |  | Send it to a Test endpoint, or send webhook.test. |
| `SECRET_UNAVAILABLE` |  | Rotate the secret with POST /api/v1/webhook-endpoints/{id}/secret, then send the request again. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UNKNOWN_TEMPLATE` |  | Use template ids from GET /api/v1/templates. |
| `UNSAFE_URL` |  | Use a public https URL. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `WEBHOOK_CAPTURE_NOT_FOUND` |  | List the endpoint's captures with GET /api/v1/webhook-endpoints/{id}/captures. |
| `WEBHOOK_ENDPOINT_LIMIT` |  | Delete one first. |
| `WEBHOOK_ENDPOINT_NOT_FOUND` |  | Check the id with GET /api/v1/webhook-endpoints. |

```sh
curl -X GET "https://passbook.mobile/api/v1/webhook-endpoints" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

Response example:

```json
{
  "items": [
    {
      "id": "0193a1b2-7c00-7000-8000-0000000000f1",
      "orgId": "0193a1b2-7c00-7000-8000-0000000000a1",
      "mode": "test",
      "url": "https://hooks.example.com/passbook",
      "urlMasked": "https://hooks.example.com/…",
      "description": "Order system",
      "eventTypes": [
        "pass.issued",
        "pass.scanned"
      ],
      "templateIds": null,
      "apiVersion": "2026-12-01",
      "status": "active",
      "target": "url",
      "failingSince": null,
      "disabledAt": null,
      "lastSuccessAt": null,
      "lastFailureAt": null,
      "lastStatus": null,
      "secretCreatedAt": 1764000000000,
      "previousSecretExpiresAt": null,
      "createdAt": 1764000000000
    }
  ],
  "nextCursor": null
}
```

## Create a webhook endpoint {#create}

`POST /api/v1/webhook-endpoints`

Creates an endpoint for events of this mode. The signing `secret` is shown once. Send `?validate=1` to check the body without creating anything.

Scopes: `webhooks:manage`. SDK name: `pb.webhookEndpoints.create`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `validate` | query | "1" |  |  |
| `url` | body | string · max 2048 | yes |  |
| `eventTypes` | body | "pass.issued" \| "pass.updated" \| "pass.voided" \| "pass.unvoided" \| "pass.removed" \| "pass.restored" \| "pass.installed" \| "pass.uninstalled" \| "pass.scanned" \| "pass.scan_refused" \| "pass.scan_undone" \| "pass.channels_changed" \| "pass.printed" \| "pass.print_voided" \| "push.failed" \| "email.failed"[] | yes |  |
| `orgId` | body | string · max 64 |  |  |
| `description` | body | string · max 120 |  |  |
| `templateIds` | body | array \| null |  |  |

Returns `201`, a `WebhookEndpointCreated`.

| Code | Status | Fix |
| --- | --- | --- |
| `CAPTURE_DEVELOPER_ONLY` |  | Make your sandbox in the developer portal and call this in Test mode. |
| `CAPTURE_NOT_STORED` |  | Send the request again. |
| `CAPTURE_TOO_LARGE` |  | Send a smaller body. |
| `CAPTURE_URL_FIXED` |  | Leave the url out, or create a URL endpoint instead. |
| `DELIVERY_PENDING` |  | Wait for it to send, then check GET /api/v1/webhook-endpoints/{id}/deliveries before replaying. |
| `EVENT_NOT_FOUND` |  | Check the id with GET /api/v1/scan/events. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_CURSOR` |  | Pass the nextCursor from the previous page unchanged, or drop it to start over. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_A_CAPTURE_ENDPOINT` |  | Use a capture endpoint: POST /api/v1/webhook-endpoints/capture returns your sandbox's. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `REPLAY_NOT_QUEUED` |  | Send the replay request again. |
| `REPLAY_TOO_LARGE` |  | Narrow the time range or replay in several smaller requests. |
| `RETENTION_RECEIPT_BUSY` |  | Wait a few seconds and send the request again. |
| `SAMPLE_EVENT_LIVE` |  | Send it to a Test endpoint, or send webhook.test. |
| `SECRET_UNAVAILABLE` |  | Rotate the secret with POST /api/v1/webhook-endpoints/{id}/secret, then send the request again. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UNKNOWN_TEMPLATE` |  | Use template ids from GET /api/v1/templates. |
| `UNSAFE_URL` |  | Use a public https URL. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `WEBHOOK_CAPTURE_NOT_FOUND` |  | List the endpoint's captures with GET /api/v1/webhook-endpoints/{id}/captures. |
| `WEBHOOK_ENDPOINT_LIMIT` |  | Delete one first. |
| `WEBHOOK_ENDPOINT_NOT_FOUND` |  | Check the id with GET /api/v1/webhook-endpoints. |

```sh
curl -X POST "https://passbook.mobile/api/v1/webhook-endpoints" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://hooks.example.com/passbook",
  "description": "Order system",
  "eventTypes": [
    "pass.issued",
    "pass.scanned"
  ]
}'
```

Response example:

```json
{
  "endpoint": {
    "id": "0193a1b2-7c00-7000-8000-0000000000f1",
    "orgId": "0193a1b2-7c00-7000-8000-0000000000a1",
    "mode": "test",
    "url": "https://hooks.example.com/passbook",
    "urlMasked": "https://hooks.example.com/…",
    "description": "Order system",
    "eventTypes": [
      "pass.issued",
      "pass.scanned"
    ],
    "templateIds": null,
    "apiVersion": "2026-12-01",
    "status": "active",
    "target": "url",
    "failingSince": null,
    "disabledAt": null,
    "lastSuccessAt": null,
    "lastFailureAt": null,
    "lastStatus": null,
    "secretCreatedAt": 1764000000000,
    "previousSecretExpiresAt": null,
    "createdAt": 1764000000000
  },
  "secret": "whsec_example_0000000000000000000000000000"
}
```

## Webhook endpoint {#retrieve}

`GET /api/v1/webhook-endpoints/{id}`

One endpoint. The signing secret is never returned.

Scopes: `webhooks:manage`. SDK name: `pb.webhookEndpoints.retrieve`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |

Returns `200`, a `WebhookEndpoint`.

| Code | Status | Fix |
| --- | --- | --- |
| `CAPTURE_DEVELOPER_ONLY` |  | Make your sandbox in the developer portal and call this in Test mode. |
| `CAPTURE_NOT_STORED` |  | Send the request again. |
| `CAPTURE_TOO_LARGE` |  | Send a smaller body. |
| `CAPTURE_URL_FIXED` |  | Leave the url out, or create a URL endpoint instead. |
| `DELIVERY_PENDING` |  | Wait for it to send, then check GET /api/v1/webhook-endpoints/{id}/deliveries before replaying. |
| `EVENT_NOT_FOUND` |  | Check the id with GET /api/v1/scan/events. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_CURSOR` |  | Pass the nextCursor from the previous page unchanged, or drop it to start over. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_A_CAPTURE_ENDPOINT` |  | Use a capture endpoint: POST /api/v1/webhook-endpoints/capture returns your sandbox's. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `REPLAY_NOT_QUEUED` |  | Send the replay request again. |
| `REPLAY_TOO_LARGE` |  | Narrow the time range or replay in several smaller requests. |
| `RETENTION_RECEIPT_BUSY` |  | Wait a few seconds and send the request again. |
| `SAMPLE_EVENT_LIVE` |  | Send it to a Test endpoint, or send webhook.test. |
| `SECRET_UNAVAILABLE` |  | Rotate the secret with POST /api/v1/webhook-endpoints/{id}/secret, then send the request again. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UNKNOWN_TEMPLATE` |  | Use template ids from GET /api/v1/templates. |
| `UNSAFE_URL` |  | Use a public https URL. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `WEBHOOK_CAPTURE_NOT_FOUND` |  | List the endpoint's captures with GET /api/v1/webhook-endpoints/{id}/captures. |
| `WEBHOOK_ENDPOINT_LIMIT` |  | Delete one first. |
| `WEBHOOK_ENDPOINT_NOT_FOUND` |  | Check the id with GET /api/v1/webhook-endpoints. |

```sh
curl -X GET "https://passbook.mobile/api/v1/webhook-endpoints/0193a1b2-7c00-7000-8000-0000000000e1" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

Response example:

```json
{
  "id": "0193a1b2-7c00-7000-8000-0000000000f1",
  "orgId": "0193a1b2-7c00-7000-8000-0000000000a1",
  "mode": "test",
  "url": "https://hooks.example.com/passbook",
  "urlMasked": "https://hooks.example.com/…",
  "description": "Order system",
  "eventTypes": [
    "pass.issued",
    "pass.scanned"
  ],
  "templateIds": null,
  "apiVersion": "2026-12-01",
  "status": "active",
  "target": "url",
  "failingSince": null,
  "disabledAt": null,
  "lastSuccessAt": null,
  "lastFailureAt": null,
  "lastStatus": null,
  "secretCreatedAt": 1764000000000,
  "previousSecretExpiresAt": null,
  "createdAt": 1764000000000
}
```

## Update, pause or resume a webhook endpoint {#update}

`PATCH /api/v1/webhook-endpoints/{id}`

Changes an endpoint, or pauses or resumes it with `status`. A disabled endpoint resumes with `active`.

Scopes: `webhooks:manage`. SDK name: `pb.webhookEndpoints.update`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `url` | body | string · max 2048 |  |  |
| `description` | body | "" \| string · max 120 |  |  |
| `eventTypes` | body | "pass.issued" \| "pass.updated" \| "pass.voided" \| "pass.unvoided" \| "pass.removed" \| "pass.restored" \| "pass.installed" \| "pass.uninstalled" \| "pass.scanned" \| "pass.scan_refused" \| "pass.scan_undone" \| "pass.channels_changed" \| "pass.printed" \| "pass.print_voided" \| "push.failed" \| "email.failed"[] |  |  |
| `templateIds` | body | array \| null |  |  |
| `status` | body | "active" \| "paused" |  |  |
| `apiVersion` | body | "2026-12-01" |  |  |

Returns `200`, a `WebhookEndpoint`.

| Code | Status | Fix |
| --- | --- | --- |
| `CAPTURE_DEVELOPER_ONLY` |  | Make your sandbox in the developer portal and call this in Test mode. |
| `CAPTURE_NOT_STORED` |  | Send the request again. |
| `CAPTURE_TOO_LARGE` |  | Send a smaller body. |
| `CAPTURE_URL_FIXED` |  | Leave the url out, or create a URL endpoint instead. |
| `DELIVERY_PENDING` |  | Wait for it to send, then check GET /api/v1/webhook-endpoints/{id}/deliveries before replaying. |
| `EVENT_NOT_FOUND` |  | Check the id with GET /api/v1/scan/events. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_CURSOR` |  | Pass the nextCursor from the previous page unchanged, or drop it to start over. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_A_CAPTURE_ENDPOINT` |  | Use a capture endpoint: POST /api/v1/webhook-endpoints/capture returns your sandbox's. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `REPLAY_NOT_QUEUED` |  | Send the replay request again. |
| `REPLAY_TOO_LARGE` |  | Narrow the time range or replay in several smaller requests. |
| `RETENTION_RECEIPT_BUSY` |  | Wait a few seconds and send the request again. |
| `SAMPLE_EVENT_LIVE` |  | Send it to a Test endpoint, or send webhook.test. |
| `SECRET_UNAVAILABLE` |  | Rotate the secret with POST /api/v1/webhook-endpoints/{id}/secret, then send the request again. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UNKNOWN_TEMPLATE` |  | Use template ids from GET /api/v1/templates. |
| `UNSAFE_URL` |  | Use a public https URL. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `WEBHOOK_CAPTURE_NOT_FOUND` |  | List the endpoint's captures with GET /api/v1/webhook-endpoints/{id}/captures. |
| `WEBHOOK_ENDPOINT_LIMIT` |  | Delete one first. |
| `WEBHOOK_ENDPOINT_NOT_FOUND` |  | Check the id with GET /api/v1/webhook-endpoints. |

```sh
curl -X PATCH "https://passbook.mobile/api/v1/webhook-endpoints/0193a1b2-7c00-7000-8000-0000000000e1" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "paused"
}'
```

Response example:

```json
{
  "id": "0193a1b2-7c00-7000-8000-0000000000f1",
  "orgId": "0193a1b2-7c00-7000-8000-0000000000a1",
  "mode": "test",
  "url": "https://hooks.example.com/passbook",
  "urlMasked": "https://hooks.example.com/…",
  "description": "Order system",
  "eventTypes": [
    "pass.issued",
    "pass.scanned"
  ],
  "templateIds": null,
  "apiVersion": "2026-12-01",
  "status": "paused",
  "target": "url",
  "failingSince": null,
  "disabledAt": null,
  "lastSuccessAt": null,
  "lastFailureAt": null,
  "lastStatus": null,
  "secretCreatedAt": 1764000000000,
  "previousSecretExpiresAt": null,
  "createdAt": 1764000000000
}
```

## Delete a webhook endpoint {#delete}

`DELETE /api/v1/webhook-endpoints/{id}`

Deletes an endpoint and its delivery history.

Scopes: `webhooks:manage`. SDK name: `pb.webhookEndpoints.delete`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `CAPTURE_DEVELOPER_ONLY` |  | Make your sandbox in the developer portal and call this in Test mode. |
| `CAPTURE_NOT_STORED` |  | Send the request again. |
| `CAPTURE_TOO_LARGE` |  | Send a smaller body. |
| `CAPTURE_URL_FIXED` |  | Leave the url out, or create a URL endpoint instead. |
| `DELIVERY_PENDING` |  | Wait for it to send, then check GET /api/v1/webhook-endpoints/{id}/deliveries before replaying. |
| `EVENT_NOT_FOUND` |  | Check the id with GET /api/v1/scan/events. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_CURSOR` |  | Pass the nextCursor from the previous page unchanged, or drop it to start over. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_A_CAPTURE_ENDPOINT` |  | Use a capture endpoint: POST /api/v1/webhook-endpoints/capture returns your sandbox's. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `REPLAY_NOT_QUEUED` |  | Send the replay request again. |
| `REPLAY_TOO_LARGE` |  | Narrow the time range or replay in several smaller requests. |
| `RETENTION_RECEIPT_BUSY` |  | Wait a few seconds and send the request again. |
| `SAMPLE_EVENT_LIVE` |  | Send it to a Test endpoint, or send webhook.test. |
| `SECRET_UNAVAILABLE` |  | Rotate the secret with POST /api/v1/webhook-endpoints/{id}/secret, then send the request again. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UNKNOWN_TEMPLATE` |  | Use template ids from GET /api/v1/templates. |
| `UNSAFE_URL` |  | Use a public https URL. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `WEBHOOK_CAPTURE_NOT_FOUND` |  | List the endpoint's captures with GET /api/v1/webhook-endpoints/{id}/captures. |
| `WEBHOOK_ENDPOINT_LIMIT` |  | Delete one first. |
| `WEBHOOK_ENDPOINT_NOT_FOUND` |  | Check the id with GET /api/v1/webhook-endpoints. |

```sh
curl -X DELETE "https://passbook.mobile/api/v1/webhook-endpoints/0193a1b2-7c00-7000-8000-0000000000e1" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

Response example:

```json
{
  "ok": true
}
```

## Rotate the signing secret {#rotateSecret}

`POST /api/v1/webhook-endpoints/{id}/secret`

Rotates the signing secret and returns the new one once. The old secret stays valid for `overlapHours` (default 24).

Scopes: `webhooks:manage`. SDK name: `pb.webhookEndpoints.rotateSecret`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `overlapHours` | body | 0 \| 24 \| 72 |  |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `CAPTURE_DEVELOPER_ONLY` |  | Make your sandbox in the developer portal and call this in Test mode. |
| `CAPTURE_NOT_STORED` |  | Send the request again. |
| `CAPTURE_TOO_LARGE` |  | Send a smaller body. |
| `CAPTURE_URL_FIXED` |  | Leave the url out, or create a URL endpoint instead. |
| `DELIVERY_PENDING` |  | Wait for it to send, then check GET /api/v1/webhook-endpoints/{id}/deliveries before replaying. |
| `EVENT_NOT_FOUND` |  | Check the id with GET /api/v1/scan/events. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_CURSOR` |  | Pass the nextCursor from the previous page unchanged, or drop it to start over. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_A_CAPTURE_ENDPOINT` |  | Use a capture endpoint: POST /api/v1/webhook-endpoints/capture returns your sandbox's. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `REPLAY_NOT_QUEUED` |  | Send the replay request again. |
| `REPLAY_TOO_LARGE` |  | Narrow the time range or replay in several smaller requests. |
| `RETENTION_RECEIPT_BUSY` |  | Wait a few seconds and send the request again. |
| `SAMPLE_EVENT_LIVE` |  | Send it to a Test endpoint, or send webhook.test. |
| `SECRET_UNAVAILABLE` |  | Rotate the secret with POST /api/v1/webhook-endpoints/{id}/secret, then send the request again. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UNKNOWN_TEMPLATE` |  | Use template ids from GET /api/v1/templates. |
| `UNSAFE_URL` |  | Use a public https URL. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `WEBHOOK_CAPTURE_NOT_FOUND` |  | List the endpoint's captures with GET /api/v1/webhook-endpoints/{id}/captures. |
| `WEBHOOK_ENDPOINT_LIMIT` |  | Delete one first. |
| `WEBHOOK_ENDPOINT_NOT_FOUND` |  | Check the id with GET /api/v1/webhook-endpoints. |

```sh
curl -X POST "https://passbook.mobile/api/v1/webhook-endpoints/0193a1b2-7c00-7000-8000-0000000000e1/secret" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "overlapHours": 24
}'
```

Response example:

```json
{
  "secret": "whsec_example_1111111111111111111111111111"
}
```

## Send a test event to this endpoint {#sendTest}

`POST /api/v1/webhook-endpoints/{id}/test`

Sends one signed event to the endpoint and reports the result. `type` is any event type and defaults to `webhook.test`; every other type carries sample data and goes to Test endpoints only. A capture endpoint stores the request and returns its `captureId`.

Scopes: `webhooks:manage`. SDK name: `pb.webhookEndpoints.sendTest`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `type` | body | "pass.issued" \| "pass.updated" \| "pass.voided" \| "pass.unvoided" \| "pass.removed" \| "pass.restored" \| "pass.installed" \| "pass.uninstalled" \| "pass.scanned" \| "pass.scan_refused" \| "pass.scan_undone" \| "pass.channels_changed" \| "pass.printed" \| "pass.print_voided" \| "push.failed" \| "email.failed" \| "webhook.test" |  |  |

Returns `200`, a `WebhookTestResult`.

| Code | Status | Fix |
| --- | --- | --- |
| `CAPTURE_DEVELOPER_ONLY` |  | Make your sandbox in the developer portal and call this in Test mode. |
| `CAPTURE_NOT_STORED` |  | Send the request again. |
| `CAPTURE_TOO_LARGE` |  | Send a smaller body. |
| `CAPTURE_URL_FIXED` |  | Leave the url out, or create a URL endpoint instead. |
| `DELIVERY_PENDING` |  | Wait for it to send, then check GET /api/v1/webhook-endpoints/{id}/deliveries before replaying. |
| `EVENT_NOT_FOUND` |  | Check the id with GET /api/v1/scan/events. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_CURSOR` |  | Pass the nextCursor from the previous page unchanged, or drop it to start over. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_A_CAPTURE_ENDPOINT` |  | Use a capture endpoint: POST /api/v1/webhook-endpoints/capture returns your sandbox's. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `REPLAY_NOT_QUEUED` |  | Send the replay request again. |
| `REPLAY_TOO_LARGE` |  | Narrow the time range or replay in several smaller requests. |
| `RETENTION_RECEIPT_BUSY` |  | Wait a few seconds and send the request again. |
| `SAMPLE_EVENT_LIVE` |  | Send it to a Test endpoint, or send webhook.test. |
| `SECRET_UNAVAILABLE` |  | Rotate the secret with POST /api/v1/webhook-endpoints/{id}/secret, then send the request again. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UNKNOWN_TEMPLATE` |  | Use template ids from GET /api/v1/templates. |
| `UNSAFE_URL` |  | Use a public https URL. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `WEBHOOK_CAPTURE_NOT_FOUND` |  | List the endpoint's captures with GET /api/v1/webhook-endpoints/{id}/captures. |
| `WEBHOOK_ENDPOINT_LIMIT` |  | Delete one first. |
| `WEBHOOK_ENDPOINT_NOT_FOUND` |  | Check the id with GET /api/v1/webhook-endpoints. |

```sh
curl -X POST "https://passbook.mobile/api/v1/webhook-endpoints/0193a1b2-7c00-7000-8000-0000000000e1/test" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "pass.updated"
}'
```

Response example:

```json
{
  "ok": true,
  "status": 200,
  "durationMs": 12,
  "errorCode": null,
  "captureId": "0193a1b2-7c00-7000-8000-0000000000d1"
}
```

## Get the sandbox's capture endpoint, making it if it has none {#ensureCapture}

`POST /api/v1/webhook-endpoints/capture`

Returns the capture endpoint of your sandbox, making it if there is none. A capture endpoint stores the signed requests PassBook would send, so you can read and verify them; it sends nothing and takes nothing from outside. Sandbox orgs in Test mode only. The signing `secret` is shown once, on creation; later calls return `secret: null`.

Scopes: `webhooks:manage`. SDK name: `pb.webhookEndpoints.ensureCapture`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgId` | body | string · max 64 |  |  |
| `eventTypes` | body | "pass.issued" \| "pass.updated" \| "pass.voided" \| "pass.unvoided" \| "pass.removed" \| "pass.restored" \| "pass.installed" \| "pass.uninstalled" \| "pass.scanned" \| "pass.scan_refused" \| "pass.scan_undone" \| "pass.channels_changed" \| "pass.printed" \| "pass.print_voided" \| "push.failed" \| "email.failed"[] |  |  |

Returns `201`, a `CaptureEndpointCreated`.

| Code | Status | Fix |
| --- | --- | --- |
| `CAPTURE_DEVELOPER_ONLY` |  | Make your sandbox in the developer portal and call this in Test mode. |
| `CAPTURE_NOT_STORED` |  | Send the request again. |
| `CAPTURE_TOO_LARGE` |  | Send a smaller body. |
| `CAPTURE_URL_FIXED` |  | Leave the url out, or create a URL endpoint instead. |
| `DELIVERY_PENDING` |  | Wait for it to send, then check GET /api/v1/webhook-endpoints/{id}/deliveries before replaying. |
| `EVENT_NOT_FOUND` |  | Check the id with GET /api/v1/scan/events. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_CURSOR` |  | Pass the nextCursor from the previous page unchanged, or drop it to start over. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_A_CAPTURE_ENDPOINT` |  | Use a capture endpoint: POST /api/v1/webhook-endpoints/capture returns your sandbox's. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `REPLAY_NOT_QUEUED` |  | Send the replay request again. |
| `REPLAY_TOO_LARGE` |  | Narrow the time range or replay in several smaller requests. |
| `RETENTION_RECEIPT_BUSY` |  | Wait a few seconds and send the request again. |
| `SAMPLE_EVENT_LIVE` |  | Send it to a Test endpoint, or send webhook.test. |
| `SECRET_UNAVAILABLE` |  | Rotate the secret with POST /api/v1/webhook-endpoints/{id}/secret, then send the request again. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UNKNOWN_TEMPLATE` |  | Use template ids from GET /api/v1/templates. |
| `UNSAFE_URL` |  | Use a public https URL. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `WEBHOOK_CAPTURE_NOT_FOUND` |  | List the endpoint's captures with GET /api/v1/webhook-endpoints/{id}/captures. |
| `WEBHOOK_ENDPOINT_LIMIT` |  | Delete one first. |
| `WEBHOOK_ENDPOINT_NOT_FOUND` |  | Check the id with GET /api/v1/webhook-endpoints. |

```sh
curl -X POST "https://passbook.mobile/api/v1/webhook-endpoints/capture" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "eventTypes": [
    "pass.issued",
    "pass.updated"
  ]
}'
```

Response example:

```json
{
  "endpoint": {
    "id": "0193a1b2-7c00-7000-8000-0000000000f2",
    "orgId": "0193a1b2-7c00-7000-8000-0000000000a1",
    "mode": "test",
    "url": "https://capture.invalid/",
    "urlMasked": "capture.invalid",
    "description": "Test capture endpoint",
    "eventTypes": [
      "pass.issued",
      "pass.updated",
      "pass.scanned"
    ],
    "templateIds": null,
    "apiVersion": "2026-12-01",
    "status": "active",
    "target": "capture",
    "failingSince": null,
    "disabledAt": null,
    "lastSuccessAt": null,
    "lastFailureAt": null,
    "lastStatus": null,
    "secretCreatedAt": 1764000000000,
    "previousSecretExpiresAt": null,
    "createdAt": 1764000000000
  },
  "secret": "whsec_example_1111111111111111111111111111"
}
```

## Requests a capture endpoint stored, newest first {#captures-list}

`GET /api/v1/webhook-endpoints/{id}/captures`

Requests a capture endpoint stored, newest first. Keeps 200 per endpoint for 7 days. Filter by `type`.

Scopes: `webhooks:manage`. SDK name: `pb.webhookEndpoints.captures.list`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `cursor` | query | string · ^\d{1,15}\.[A-Za-z0-9-]{1,64}$ |  |  |
| `limit` | query | integer · ≥ 1 · ≤ 100 |  |  |
| `type` | query | "pass.issued" \| "pass.updated" \| "pass.voided" \| "pass.unvoided" \| "pass.removed" \| "pass.restored" \| "pass.installed" \| "pass.uninstalled" \| "pass.scanned" \| "pass.scan_refused" \| "pass.scan_undone" \| "pass.channels_changed" \| "pass.printed" \| "pass.print_voided" \| "push.failed" \| "email.failed" \| "webhook.test" |  |  |

Returns `200`, a `WebhookCapturePage`.

| Code | Status | Fix |
| --- | --- | --- |
| `CAPTURE_DEVELOPER_ONLY` |  | Make your sandbox in the developer portal and call this in Test mode. |
| `CAPTURE_NOT_STORED` |  | Send the request again. |
| `CAPTURE_TOO_LARGE` |  | Send a smaller body. |
| `CAPTURE_URL_FIXED` |  | Leave the url out, or create a URL endpoint instead. |
| `DELIVERY_PENDING` |  | Wait for it to send, then check GET /api/v1/webhook-endpoints/{id}/deliveries before replaying. |
| `EVENT_NOT_FOUND` |  | Check the id with GET /api/v1/scan/events. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_CURSOR` |  | Pass the nextCursor from the previous page unchanged, or drop it to start over. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_A_CAPTURE_ENDPOINT` |  | Use a capture endpoint: POST /api/v1/webhook-endpoints/capture returns your sandbox's. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `REPLAY_NOT_QUEUED` |  | Send the replay request again. |
| `REPLAY_TOO_LARGE` |  | Narrow the time range or replay in several smaller requests. |
| `RETENTION_RECEIPT_BUSY` |  | Wait a few seconds and send the request again. |
| `SAMPLE_EVENT_LIVE` |  | Send it to a Test endpoint, or send webhook.test. |
| `SECRET_UNAVAILABLE` |  | Rotate the secret with POST /api/v1/webhook-endpoints/{id}/secret, then send the request again. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UNKNOWN_TEMPLATE` |  | Use template ids from GET /api/v1/templates. |
| `UNSAFE_URL` |  | Use a public https URL. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `WEBHOOK_CAPTURE_NOT_FOUND` |  | List the endpoint's captures with GET /api/v1/webhook-endpoints/{id}/captures. |
| `WEBHOOK_ENDPOINT_LIMIT` |  | Delete one first. |
| `WEBHOOK_ENDPOINT_NOT_FOUND` |  | Check the id with GET /api/v1/webhook-endpoints. |

```sh
curl -X GET "https://passbook.mobile/api/v1/webhook-endpoints/0193a1b2-7c00-7000-8000-0000000000e1/captures?limit=25" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

Response example:

```json
{
  "items": [
    {
      "id": "0193a1b2-7c00-7000-8000-0000000000d1",
      "endpointId": "0193a1b2-7c00-7000-8000-0000000000f2",
      "eventId": "0193a1b2-7c00-7000-8000-0000000000e2",
      "type": "pass.updated",
      "trigger": "test",
      "status": 200,
      "durationMs": 12,
      "headers": {
        "content-type": "application/json",
        "user-agent": "PassBook-Webhooks/1.0",
        "x-passbook-event-id": "0193a1b2-7c00-7000-8000-0000000000e2",
        "x-passbook-event-type": "pass.updated",
        "x-passbook-timestamp": "1764000000",
        "x-passbook-signature": "v1=5f2c0e9a1b7d4c3e8a6f0d2b9c4e1a7f3d5b8c0e2a4f6d8b1c3e5a7f9b0d2c4e"
      },
      "body": "{\"id\":\"0193a1b2-7c00-7000-8000-0000000000e2\",\"type\":\"pass.updated\"}",
      "createdAt": 1764000000000
    }
  ],
  "nextCursor": null
}
```

## One stored request: headers and the raw body {#captures-retrieve}

`GET /api/v1/webhook-endpoints/{id}/captures/{captureId}`

One stored request: the exact headers and raw body. Verify the signature over these bytes.

Scopes: `webhooks:manage`. SDK name: `pb.webhookEndpoints.captures.retrieve`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `captureId` | path | string · max 64 | yes |  |

Returns `200`, a `WebhookCapture`.

| Code | Status | Fix |
| --- | --- | --- |
| `CAPTURE_DEVELOPER_ONLY` |  | Make your sandbox in the developer portal and call this in Test mode. |
| `CAPTURE_NOT_STORED` |  | Send the request again. |
| `CAPTURE_TOO_LARGE` |  | Send a smaller body. |
| `CAPTURE_URL_FIXED` |  | Leave the url out, or create a URL endpoint instead. |
| `DELIVERY_PENDING` |  | Wait for it to send, then check GET /api/v1/webhook-endpoints/{id}/deliveries before replaying. |
| `EVENT_NOT_FOUND` |  | Check the id with GET /api/v1/scan/events. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_CURSOR` |  | Pass the nextCursor from the previous page unchanged, or drop it to start over. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_A_CAPTURE_ENDPOINT` |  | Use a capture endpoint: POST /api/v1/webhook-endpoints/capture returns your sandbox's. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `REPLAY_NOT_QUEUED` |  | Send the replay request again. |
| `REPLAY_TOO_LARGE` |  | Narrow the time range or replay in several smaller requests. |
| `RETENTION_RECEIPT_BUSY` |  | Wait a few seconds and send the request again. |
| `SAMPLE_EVENT_LIVE` |  | Send it to a Test endpoint, or send webhook.test. |
| `SECRET_UNAVAILABLE` |  | Rotate the secret with POST /api/v1/webhook-endpoints/{id}/secret, then send the request again. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UNKNOWN_TEMPLATE` |  | Use template ids from GET /api/v1/templates. |
| `UNSAFE_URL` |  | Use a public https URL. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `WEBHOOK_CAPTURE_NOT_FOUND` |  | List the endpoint's captures with GET /api/v1/webhook-endpoints/{id}/captures. |
| `WEBHOOK_ENDPOINT_LIMIT` |  | Delete one first. |
| `WEBHOOK_ENDPOINT_NOT_FOUND` |  | Check the id with GET /api/v1/webhook-endpoints. |

```sh
curl -X GET "https://passbook.mobile/api/v1/webhook-endpoints/0193a1b2-7c00-7000-8000-0000000000e1/captures/0193a1b2-7c00-7000-8000-0000000000e1" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

Response example:

```json
{
  "id": "0193a1b2-7c00-7000-8000-0000000000d1",
  "endpointId": "0193a1b2-7c00-7000-8000-0000000000f2",
  "eventId": "0193a1b2-7c00-7000-8000-0000000000e2",
  "type": "pass.updated",
  "trigger": "test",
  "status": 200,
  "durationMs": 12,
  "headers": {
    "content-type": "application/json",
    "user-agent": "PassBook-Webhooks/1.0",
    "x-passbook-event-id": "0193a1b2-7c00-7000-8000-0000000000e2",
    "x-passbook-event-type": "pass.updated",
    "x-passbook-timestamp": "1764000000",
    "x-passbook-signature": "v1=5f2c0e9a1b7d4c3e8a6f0d2b9c4e1a7f3d5b8c0e2a4f6d8b1c3e5a7f9b0d2c4e"
  },
  "body": "{\"id\":\"0193a1b2-7c00-7000-8000-0000000000e2\",\"type\":\"pass.updated\"}",
  "createdAt": 1764000000000
}
```

## Sign a stored request again and store it as a new capture {#captures-replay}

`POST /api/v1/webhook-endpoints/{id}/captures/{captureId}/replay`

Signs a stored request again with a fresh timestamp and stores it as a new capture with the same event id.

Scopes: `webhooks:manage`. SDK name: `pb.webhookEndpoints.captures.replay`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `captureId` | path | string · max 64 | yes |  |

Returns `201`, a `WebhookCapture`.

| Code | Status | Fix |
| --- | --- | --- |
| `CAPTURE_DEVELOPER_ONLY` |  | Make your sandbox in the developer portal and call this in Test mode. |
| `CAPTURE_NOT_STORED` |  | Send the request again. |
| `CAPTURE_TOO_LARGE` |  | Send a smaller body. |
| `CAPTURE_URL_FIXED` |  | Leave the url out, or create a URL endpoint instead. |
| `DELIVERY_PENDING` |  | Wait for it to send, then check GET /api/v1/webhook-endpoints/{id}/deliveries before replaying. |
| `EVENT_NOT_FOUND` |  | Check the id with GET /api/v1/scan/events. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_CURSOR` |  | Pass the nextCursor from the previous page unchanged, or drop it to start over. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_A_CAPTURE_ENDPOINT` |  | Use a capture endpoint: POST /api/v1/webhook-endpoints/capture returns your sandbox's. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `REPLAY_NOT_QUEUED` |  | Send the replay request again. |
| `REPLAY_TOO_LARGE` |  | Narrow the time range or replay in several smaller requests. |
| `RETENTION_RECEIPT_BUSY` |  | Wait a few seconds and send the request again. |
| `SAMPLE_EVENT_LIVE` |  | Send it to a Test endpoint, or send webhook.test. |
| `SECRET_UNAVAILABLE` |  | Rotate the secret with POST /api/v1/webhook-endpoints/{id}/secret, then send the request again. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UNKNOWN_TEMPLATE` |  | Use template ids from GET /api/v1/templates. |
| `UNSAFE_URL` |  | Use a public https URL. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `WEBHOOK_CAPTURE_NOT_FOUND` |  | List the endpoint's captures with GET /api/v1/webhook-endpoints/{id}/captures. |
| `WEBHOOK_ENDPOINT_LIMIT` |  | Delete one first. |
| `WEBHOOK_ENDPOINT_NOT_FOUND` |  | Check the id with GET /api/v1/webhook-endpoints. |

```sh
curl -X POST "https://passbook.mobile/api/v1/webhook-endpoints/0193a1b2-7c00-7000-8000-0000000000e1/captures/0193a1b2-7c00-7000-8000-0000000000e1/replay" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

Response example:

```json
{
  "id": "0193a1b2-7c00-7000-8000-0000000000d1",
  "endpointId": "0193a1b2-7c00-7000-8000-0000000000f2",
  "eventId": "0193a1b2-7c00-7000-8000-0000000000e2",
  "type": "pass.updated",
  "trigger": "test",
  "status": 200,
  "durationMs": 12,
  "headers": {
    "content-type": "application/json",
    "user-agent": "PassBook-Webhooks/1.0",
    "x-passbook-event-id": "0193a1b2-7c00-7000-8000-0000000000e2",
    "x-passbook-event-type": "pass.updated",
    "x-passbook-timestamp": "1764000000",
    "x-passbook-signature": "v1=5f2c0e9a1b7d4c3e8a6f0d2b9c4e1a7f3d5b8c0e2a4f6d8b1c3e5a7f9b0d2c4e"
  },
  "body": "{\"id\":\"0193a1b2-7c00-7000-8000-0000000000e2\",\"type\":\"pass.updated\"}",
  "createdAt": 1764000000000
}
```

## Read a capture endpoint's current signing secret {#captures-revealSecret}

`POST /api/v1/webhook-endpoints/{id}/captures/secret`

Returns the current signing secret of a capture endpoint, so you can verify its captures. It protects nothing outside your sandbox.

Scopes: `webhooks:manage`. SDK name: `pb.webhookEndpoints.captures.revealSecret`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |

Returns `200`, a `CaptureSecret`.

| Code | Status | Fix |
| --- | --- | --- |
| `CAPTURE_DEVELOPER_ONLY` |  | Make your sandbox in the developer portal and call this in Test mode. |
| `CAPTURE_NOT_STORED` |  | Send the request again. |
| `CAPTURE_TOO_LARGE` |  | Send a smaller body. |
| `CAPTURE_URL_FIXED` |  | Leave the url out, or create a URL endpoint instead. |
| `DELIVERY_PENDING` |  | Wait for it to send, then check GET /api/v1/webhook-endpoints/{id}/deliveries before replaying. |
| `EVENT_NOT_FOUND` |  | Check the id with GET /api/v1/scan/events. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_CURSOR` |  | Pass the nextCursor from the previous page unchanged, or drop it to start over. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_A_CAPTURE_ENDPOINT` |  | Use a capture endpoint: POST /api/v1/webhook-endpoints/capture returns your sandbox's. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `REPLAY_NOT_QUEUED` |  | Send the replay request again. |
| `REPLAY_TOO_LARGE` |  | Narrow the time range or replay in several smaller requests. |
| `RETENTION_RECEIPT_BUSY` |  | Wait a few seconds and send the request again. |
| `SAMPLE_EVENT_LIVE` |  | Send it to a Test endpoint, or send webhook.test. |
| `SECRET_UNAVAILABLE` |  | Rotate the secret with POST /api/v1/webhook-endpoints/{id}/secret, then send the request again. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UNKNOWN_TEMPLATE` |  | Use template ids from GET /api/v1/templates. |
| `UNSAFE_URL` |  | Use a public https URL. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `WEBHOOK_CAPTURE_NOT_FOUND` |  | List the endpoint's captures with GET /api/v1/webhook-endpoints/{id}/captures. |
| `WEBHOOK_ENDPOINT_LIMIT` |  | Delete one first. |
| `WEBHOOK_ENDPOINT_NOT_FOUND` |  | Check the id with GET /api/v1/webhook-endpoints. |

```sh
curl -X POST "https://passbook.mobile/api/v1/webhook-endpoints/0193a1b2-7c00-7000-8000-0000000000e1/captures/secret" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

Response example:

```json
{
  "secret": "whsec_example_1111111111111111111111111111"
}
```

## Deliveries of an endpoint, newest first {#deliveries-list}

`GET /api/v1/webhook-endpoints/{id}/deliveries`

Deliveries of an endpoint, newest first. Filter by `state` or `type`.

Scopes: `webhooks:manage`. SDK name: `pb.webhookEndpoints.deliveries.list`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `cursor` | query | string · max 512 |  |  |
| `limit` | query | integer · ≥ 1 · ≤ 200 |  |  |
| `state` | query | "pending" \| "delivered" \| "failed" \| "cancelled" |  |  |
| `type` | query | "pass.issued" \| "pass.updated" \| "pass.voided" \| "pass.unvoided" \| "pass.removed" \| "pass.restored" \| "pass.installed" \| "pass.uninstalled" \| "pass.scanned" \| "pass.scan_refused" \| "pass.scan_undone" \| "pass.channels_changed" \| "pass.printed" \| "pass.print_voided" \| "push.failed" \| "email.failed" \| "webhook.test" |  |  |

Returns `200`, a `WebhookDeliveryPage`.

| Code | Status | Fix |
| --- | --- | --- |
| `CAPTURE_DEVELOPER_ONLY` |  | Make your sandbox in the developer portal and call this in Test mode. |
| `CAPTURE_NOT_STORED` |  | Send the request again. |
| `CAPTURE_TOO_LARGE` |  | Send a smaller body. |
| `CAPTURE_URL_FIXED` |  | Leave the url out, or create a URL endpoint instead. |
| `DELIVERY_PENDING` |  | Wait for it to send, then check GET /api/v1/webhook-endpoints/{id}/deliveries before replaying. |
| `EVENT_NOT_FOUND` |  | Check the id with GET /api/v1/scan/events. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_CURSOR` |  | Pass the nextCursor from the previous page unchanged, or drop it to start over. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_A_CAPTURE_ENDPOINT` |  | Use a capture endpoint: POST /api/v1/webhook-endpoints/capture returns your sandbox's. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `REPLAY_NOT_QUEUED` |  | Send the replay request again. |
| `REPLAY_TOO_LARGE` |  | Narrow the time range or replay in several smaller requests. |
| `RETENTION_RECEIPT_BUSY` |  | Wait a few seconds and send the request again. |
| `SAMPLE_EVENT_LIVE` |  | Send it to a Test endpoint, or send webhook.test. |
| `SECRET_UNAVAILABLE` |  | Rotate the secret with POST /api/v1/webhook-endpoints/{id}/secret, then send the request again. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UNKNOWN_TEMPLATE` |  | Use template ids from GET /api/v1/templates. |
| `UNSAFE_URL` |  | Use a public https URL. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `WEBHOOK_CAPTURE_NOT_FOUND` |  | List the endpoint's captures with GET /api/v1/webhook-endpoints/{id}/captures. |
| `WEBHOOK_ENDPOINT_LIMIT` |  | Delete one first. |
| `WEBHOOK_ENDPOINT_NOT_FOUND` |  | Check the id with GET /api/v1/webhook-endpoints. |

```sh
curl -X GET "https://passbook.mobile/api/v1/webhook-endpoints/0193a1b2-7c00-7000-8000-0000000000e1/deliveries?limit=25" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

Response example:

```json
{
  "items": [
    {
      "eventId": "0193a1b2-7c00-7000-8000-0000000000e1",
      "type": "pass.issued",
      "passId": "0193a1b2-7c00-7000-8000-0000000000c1",
      "externalId": "booking_8841",
      "state": "delivered",
      "attempts": 1,
      "nextAt": 1764000000000,
      "lastStatus": 200,
      "lastError": null,
      "lastAttemptAt": 1764000000000,
      "finishedAt": 1764000000000,
      "replays": 0
    }
  ],
  "nextCursor": null
}
```

## One delivery with its attempts and payload {#deliveries-retrieve}

`GET /api/v1/webhook-endpoints/{id}/deliveries/{eventId}`

One delivery with every attempt and the payload sent.

Scopes: `webhooks:manage`. SDK name: `pb.webhookEndpoints.deliveries.retrieve`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `eventId` | path | string · max 64 | yes |  |

Returns `200`, a `WebhookDeliveryDetail`.

| Code | Status | Fix |
| --- | --- | --- |
| `CAPTURE_DEVELOPER_ONLY` |  | Make your sandbox in the developer portal and call this in Test mode. |
| `CAPTURE_NOT_STORED` |  | Send the request again. |
| `CAPTURE_TOO_LARGE` |  | Send a smaller body. |
| `CAPTURE_URL_FIXED` |  | Leave the url out, or create a URL endpoint instead. |
| `DELIVERY_PENDING` |  | Wait for it to send, then check GET /api/v1/webhook-endpoints/{id}/deliveries before replaying. |
| `EVENT_NOT_FOUND` |  | Check the id with GET /api/v1/scan/events. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_CURSOR` |  | Pass the nextCursor from the previous page unchanged, or drop it to start over. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_A_CAPTURE_ENDPOINT` |  | Use a capture endpoint: POST /api/v1/webhook-endpoints/capture returns your sandbox's. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `REPLAY_NOT_QUEUED` |  | Send the replay request again. |
| `REPLAY_TOO_LARGE` |  | Narrow the time range or replay in several smaller requests. |
| `RETENTION_RECEIPT_BUSY` |  | Wait a few seconds and send the request again. |
| `SAMPLE_EVENT_LIVE` |  | Send it to a Test endpoint, or send webhook.test. |
| `SECRET_UNAVAILABLE` |  | Rotate the secret with POST /api/v1/webhook-endpoints/{id}/secret, then send the request again. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UNKNOWN_TEMPLATE` |  | Use template ids from GET /api/v1/templates. |
| `UNSAFE_URL` |  | Use a public https URL. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `WEBHOOK_CAPTURE_NOT_FOUND` |  | List the endpoint's captures with GET /api/v1/webhook-endpoints/{id}/captures. |
| `WEBHOOK_ENDPOINT_LIMIT` |  | Delete one first. |
| `WEBHOOK_ENDPOINT_NOT_FOUND` |  | Check the id with GET /api/v1/webhook-endpoints. |

```sh
curl -X GET "https://passbook.mobile/api/v1/webhook-endpoints/0193a1b2-7c00-7000-8000-0000000000e1/deliveries/0193a1b2-7c00-7000-8000-0000000000e1" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

Response example:

```json
{
  "eventId": "0193a1b2-7c00-7000-8000-0000000000e1",
  "type": "pass.issued",
  "passId": "0193a1b2-7c00-7000-8000-0000000000c1",
  "externalId": "booking_8841",
  "state": "delivered",
  "attempts": 1,
  "nextAt": 1764000000000,
  "lastStatus": 200,
  "lastError": null,
  "lastAttemptAt": 1764000000000,
  "finishedAt": 1764000000000,
  "replays": 0,
  "attemptLog": [
    {
      "attempt": 1,
      "trigger": "event",
      "status": 200,
      "errorCode": null,
      "durationMs": 84,
      "at": 1764000000000
    }
  ],
  "payload": {
    "id": "0193a1b2-7c00-7000-8000-0000000000e1",
    "type": "pass.issued",
    "apiVersion": "2026-12-01",
    "createdAt": 1764000000000,
    "orgId": "0193a1b2-7c00-7000-8000-0000000000a1",
    "mode": "test",
    "pass": {
      "id": "0193a1b2-7c00-7000-8000-0000000000c1",
      "externalId": "booking_8841",
      "templateId": "0193a1b2-7c00-7000-8000-0000000000b1"
    },
    "data": {
      "version": 1,
      "source": "api"
    }
  }
}
```

## Send one delivery again {#deliveries-replay}

`POST /api/v1/webhook-endpoints/{id}/deliveries/{eventId}/replay`

Sends one delivery again with a fresh signature.

Scopes: `webhooks:manage`. SDK name: `pb.webhookEndpoints.deliveries.replay`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `eventId` | path | string · max 64 | yes |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `CAPTURE_DEVELOPER_ONLY` |  | Make your sandbox in the developer portal and call this in Test mode. |
| `CAPTURE_NOT_STORED` |  | Send the request again. |
| `CAPTURE_TOO_LARGE` |  | Send a smaller body. |
| `CAPTURE_URL_FIXED` |  | Leave the url out, or create a URL endpoint instead. |
| `DELIVERY_PENDING` |  | Wait for it to send, then check GET /api/v1/webhook-endpoints/{id}/deliveries before replaying. |
| `EVENT_NOT_FOUND` |  | Check the id with GET /api/v1/scan/events. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_CURSOR` |  | Pass the nextCursor from the previous page unchanged, or drop it to start over. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_A_CAPTURE_ENDPOINT` |  | Use a capture endpoint: POST /api/v1/webhook-endpoints/capture returns your sandbox's. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `REPLAY_NOT_QUEUED` |  | Send the replay request again. |
| `REPLAY_TOO_LARGE` |  | Narrow the time range or replay in several smaller requests. |
| `RETENTION_RECEIPT_BUSY` |  | Wait a few seconds and send the request again. |
| `SAMPLE_EVENT_LIVE` |  | Send it to a Test endpoint, or send webhook.test. |
| `SECRET_UNAVAILABLE` |  | Rotate the secret with POST /api/v1/webhook-endpoints/{id}/secret, then send the request again. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UNKNOWN_TEMPLATE` |  | Use template ids from GET /api/v1/templates. |
| `UNSAFE_URL` |  | Use a public https URL. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `WEBHOOK_CAPTURE_NOT_FOUND` |  | List the endpoint's captures with GET /api/v1/webhook-endpoints/{id}/captures. |
| `WEBHOOK_ENDPOINT_LIMIT` |  | Delete one first. |
| `WEBHOOK_ENDPOINT_NOT_FOUND` |  | Check the id with GET /api/v1/webhook-endpoints. |

```sh
curl -X POST "https://passbook.mobile/api/v1/webhook-endpoints/0193a1b2-7c00-7000-8000-0000000000e1/deliveries/0193a1b2-7c00-7000-8000-0000000000e1/replay" \
  -H "Authorization: Bearer $PASSBOOK_KEY"
```

Response example:

```json
{
  "queued": 1
}
```

## Send many deliveries again, by event time {#deliveries-bulkReplay}

`POST /api/v1/webhook-endpoints/{id}/replay`

Sends the deliveries in a time range again. `dryRun` counts without sending.

Scopes: `webhooks:manage`. SDK name: `pb.webhookEndpoints.deliveries.bulkReplay`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `from` | body | integer · ≥ 0 | yes |  |
| `to` | body | integer · ≥ 0 | yes |  |
| `include` | body | "failed" \| "failed_and_cancelled" \| "all" |  |  |
| `missing` | body | boolean |  |  |
| `dryRun` | body | boolean |  |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `CAPTURE_DEVELOPER_ONLY` |  | Make your sandbox in the developer portal and call this in Test mode. |
| `CAPTURE_NOT_STORED` |  | Send the request again. |
| `CAPTURE_TOO_LARGE` |  | Send a smaller body. |
| `CAPTURE_URL_FIXED` |  | Leave the url out, or create a URL endpoint instead. |
| `DELIVERY_PENDING` |  | Wait for it to send, then check GET /api/v1/webhook-endpoints/{id}/deliveries before replaying. |
| `EVENT_NOT_FOUND` |  | Check the id with GET /api/v1/scan/events. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `INVALID_CURSOR` |  | Pass the nextCursor from the previous page unchanged, or drop it to start over. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `NOT_A_CAPTURE_ENDPOINT` |  | Use a capture endpoint: POST /api/v1/webhook-endpoints/capture returns your sandbox's. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `REPLAY_NOT_QUEUED` |  | Send the replay request again. |
| `REPLAY_TOO_LARGE` |  | Narrow the time range or replay in several smaller requests. |
| `RETENTION_RECEIPT_BUSY` |  | Wait a few seconds and send the request again. |
| `SAMPLE_EVENT_LIVE` |  | Send it to a Test endpoint, or send webhook.test. |
| `SECRET_UNAVAILABLE` |  | Rotate the secret with POST /api/v1/webhook-endpoints/{id}/secret, then send the request again. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UNKNOWN_TEMPLATE` |  | Use template ids from GET /api/v1/templates. |
| `UNSAFE_URL` |  | Use a public https URL. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `WEBHOOK_CAPTURE_NOT_FOUND` |  | List the endpoint's captures with GET /api/v1/webhook-endpoints/{id}/captures. |
| `WEBHOOK_ENDPOINT_LIMIT` |  | Delete one first. |
| `WEBHOOK_ENDPOINT_NOT_FOUND` |  | Check the id with GET /api/v1/webhook-endpoints. |

```sh
curl -X POST "https://passbook.mobile/api/v1/webhook-endpoints/0193a1b2-7c00-7000-8000-0000000000e1/replay" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "from": 1764000000000,
  "to": 1764003600000,
  "include": "failed",
  "dryRun": true
}'
```

Response example:

```json
{
  "queued": 12
}
```
