# Connections

Connections · PassBook API reference. Authenticate with `Authorization: Bearer $PASSBOOK_KEY`.

## List connections {#list}

`GET /api/v1/connections`

Scopes: `connections:read`. SDK name: `pb.connections.list`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `health` | query | "unknown" \| "healthy" \| "degraded" \| "failing" \| "paused" \| "disabled" |  |  |
| `q` | query | string · max 200 |  |  |
| `cursor` | query | string |  |  |
| `limit` | query | integer · ≥ 1 · ≤ 200 |  |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `CONNECTION_CONFLICT` |  | Fetch it with GET /api/v1/connections/{id} and send the change again. |
| `CONNECTION_DISABLED` |  | Enable it with PATCH /api/v1/connections/{id}, then send the request again. |
| `CONNECTION_NOT_FOUND` |  | Check the id with GET /api/v1/connections. |
| `CONNECTOR_NOT_FOUND` |  | List valid types with GET /api/v1/connectors. |
| `CONNECTOR_UNKNOWN` |  | Set type to a value from GET /api/v1/connectors. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `HOLDER_EMAIL_INVALID` |  | Correct the email in the source system, then sync the connection again. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_UNSUPPORTED` |  | Create the connection in a mode the connector supports; GET /api/v1/connectors/{type} lists them. |
| `ORG_INACTIVE` |  | Reactivate it with POST /api/v1/orgs/{orgId}/reopen or ask the platform owner. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UNSAFE_URL` |  | Use a public https URL. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `WEBHOOK_ALREADY_FINISHED` |  | Do nothing; check its status with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_CONTEXT_CONFLICT` |  | Resend the event from the source system. |
| `WEBHOOK_DISPATCH_INCOMPLETE` |  | Retry with backoff. |
| `WEBHOOK_EFFECT_UNCERTAIN` |  | Resolve it with POST /api/v1/connections/{id}/webhook-failures/{retentionId}/resolve after checking the pass. |
| `WEBHOOK_ENQUEUE_FAILED` |  | Retry with backoff. |
| `WEBHOOK_ITEM_BUSY` |  | Retry with backoff. |
| `WEBHOOK_ITEM_PENDING` |  | Retry with backoff. |
| `WEBHOOK_NOTHING_TO_RESOLVE` |  | Do nothing; list failures with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_NOT_FOUND` |  | Check the retentionId with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_PAYLOAD` |  | Send the body in the format the connector documents. |
| `WEBHOOK_PAYLOAD_MISSING` |  | Retry with backoff; if it persists, resend the event from the source. |
| `WEBHOOK_REFERENCE_MODE` |  | Retry with backoff. |
| `WEBHOOK_REFERENCE_MODE_CHANGED` |  | Resend the event from the source system. |
| `WEBHOOK_RESOLVE_CONFLICT` |  | List failures again and resolve once more. |
| `WEBHOOK_RETENTION_FAILED` |  | Retry with backoff. |
| `WEBHOOK_RETENTION_UNAVAILABLE` |  | Retry with backoff. |
| `WEBHOOK_SIGNATURE` |  | Sign the body with the connection's current webhook secret. |
| `WEBHOOK_SNAPSHOT_UNAVAILABLE` |  | Resend the event from the source system instead of replaying. |
| `WEBHOOK_STALE_CONTEXT` |  | Resend the event from the source system. |
| `WEBHOOK_STILL_PENDING` |  | Wait for it to run before resolving it. |
| `WEBHOOK_UNAVAILABLE` |  | Retry the webhook. |
| `WEBHOOK_WORK_CHANGED` |  | Retry with backoff. |

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

## Create a connection {#create}

`POST /api/v1/connections`

Scopes: `connections:write`. SDK name: `pb.connections.create`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgId` | body | string · max 64 | yes |  |
| `connectorType` | body | string | yes |  |
| `name` | body | string · max 120 | yes |  |
| `config` | body | object | yes |  |
| `secrets` | body | object |  |  |
| `webhookSecret` | body | string · max 256 |  |  |
| `mapping` | body | object |  |  |
| `defaultTemplateId` | body | string · max 64 |  |  |
| `holderEmailField` | body | string · max 200 |  |  |
| `autoCreate` | body | boolean |  |  |
| `autoEmail` | body | boolean |  |  |
| `onMissing` | body | "keep" \| "flag" \| "void" |  |  |
| `voidWhen` | body | object[] |  |  |
| `mode` | body | "poll" \| "webhook" \| "hybrid" \| "manual" \| "snapshot" |  |  |
| `intervalSeconds` | body | integer · ≥ 60 |  |  |
| `maxConcurrency` | body | integer · ≥ 1 · ≤ 20 |  |  |
| `requestsPerMinute` | body | integer · ≥ 1 · ≤ 6000 |  |  |

Returns `201`.

| Code | Status | Fix |
| --- | --- | --- |
| `CONNECTION_CONFLICT` |  | Fetch it with GET /api/v1/connections/{id} and send the change again. |
| `CONNECTION_DISABLED` |  | Enable it with PATCH /api/v1/connections/{id}, then send the request again. |
| `CONNECTION_NOT_FOUND` |  | Check the id with GET /api/v1/connections. |
| `CONNECTOR_NOT_FOUND` |  | List valid types with GET /api/v1/connectors. |
| `CONNECTOR_UNKNOWN` |  | Set type to a value from GET /api/v1/connectors. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `HOLDER_EMAIL_INVALID` |  | Correct the email in the source system, then sync the connection again. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_UNSUPPORTED` |  | Create the connection in a mode the connector supports; GET /api/v1/connectors/{type} lists them. |
| `ORG_INACTIVE` |  | Reactivate it with POST /api/v1/orgs/{orgId}/reopen or ask the platform owner. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UNSAFE_URL` |  | Use a public https URL. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `WEBHOOK_ALREADY_FINISHED` |  | Do nothing; check its status with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_CONTEXT_CONFLICT` |  | Resend the event from the source system. |
| `WEBHOOK_DISPATCH_INCOMPLETE` |  | Retry with backoff. |
| `WEBHOOK_EFFECT_UNCERTAIN` |  | Resolve it with POST /api/v1/connections/{id}/webhook-failures/{retentionId}/resolve after checking the pass. |
| `WEBHOOK_ENQUEUE_FAILED` |  | Retry with backoff. |
| `WEBHOOK_ITEM_BUSY` |  | Retry with backoff. |
| `WEBHOOK_ITEM_PENDING` |  | Retry with backoff. |
| `WEBHOOK_NOTHING_TO_RESOLVE` |  | Do nothing; list failures with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_NOT_FOUND` |  | Check the retentionId with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_PAYLOAD` |  | Send the body in the format the connector documents. |
| `WEBHOOK_PAYLOAD_MISSING` |  | Retry with backoff; if it persists, resend the event from the source. |
| `WEBHOOK_REFERENCE_MODE` |  | Retry with backoff. |
| `WEBHOOK_REFERENCE_MODE_CHANGED` |  | Resend the event from the source system. |
| `WEBHOOK_RESOLVE_CONFLICT` |  | List failures again and resolve once more. |
| `WEBHOOK_RETENTION_FAILED` |  | Retry with backoff. |
| `WEBHOOK_RETENTION_UNAVAILABLE` |  | Retry with backoff. |
| `WEBHOOK_SIGNATURE` |  | Sign the body with the connection's current webhook secret. |
| `WEBHOOK_SNAPSHOT_UNAVAILABLE` |  | Resend the event from the source system instead of replaying. |
| `WEBHOOK_STALE_CONTEXT` |  | Resend the event from the source system. |
| `WEBHOOK_STILL_PENDING` |  | Wait for it to run before resolving it. |
| `WEBHOOK_UNAVAILABLE` |  | Retry the webhook. |
| `WEBHOOK_WORK_CHANGED` |  | Retry with backoff. |

```sh
curl -X POST "https://passbook.mobile/api/v1/connections" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "orgId": "0193a1b2-7c00-7000-8000-0000000000a1",
  "connectorType": "Example",
  "name": "Example",
  "config": {}
}'
```

## Connection health summary {#retrieveSummary}

`GET /api/v1/connections/summary`

Scopes: `connections:read`. SDK name: `pb.connections.retrieveSummary`.

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `CONNECTION_CONFLICT` |  | Fetch it with GET /api/v1/connections/{id} and send the change again. |
| `CONNECTION_DISABLED` |  | Enable it with PATCH /api/v1/connections/{id}, then send the request again. |
| `CONNECTION_NOT_FOUND` |  | Check the id with GET /api/v1/connections. |
| `CONNECTOR_NOT_FOUND` |  | List valid types with GET /api/v1/connectors. |
| `CONNECTOR_UNKNOWN` |  | Set type to a value from GET /api/v1/connectors. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `HOLDER_EMAIL_INVALID` |  | Correct the email in the source system, then sync the connection again. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_UNSUPPORTED` |  | Create the connection in a mode the connector supports; GET /api/v1/connectors/{type} lists them. |
| `ORG_INACTIVE` |  | Reactivate it with POST /api/v1/orgs/{orgId}/reopen or ask the platform owner. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UNSAFE_URL` |  | Use a public https URL. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `WEBHOOK_ALREADY_FINISHED` |  | Do nothing; check its status with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_CONTEXT_CONFLICT` |  | Resend the event from the source system. |
| `WEBHOOK_DISPATCH_INCOMPLETE` |  | Retry with backoff. |
| `WEBHOOK_EFFECT_UNCERTAIN` |  | Resolve it with POST /api/v1/connections/{id}/webhook-failures/{retentionId}/resolve after checking the pass. |
| `WEBHOOK_ENQUEUE_FAILED` |  | Retry with backoff. |
| `WEBHOOK_ITEM_BUSY` |  | Retry with backoff. |
| `WEBHOOK_ITEM_PENDING` |  | Retry with backoff. |
| `WEBHOOK_NOTHING_TO_RESOLVE` |  | Do nothing; list failures with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_NOT_FOUND` |  | Check the retentionId with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_PAYLOAD` |  | Send the body in the format the connector documents. |
| `WEBHOOK_PAYLOAD_MISSING` |  | Retry with backoff; if it persists, resend the event from the source. |
| `WEBHOOK_REFERENCE_MODE` |  | Retry with backoff. |
| `WEBHOOK_REFERENCE_MODE_CHANGED` |  | Resend the event from the source system. |
| `WEBHOOK_RESOLVE_CONFLICT` |  | List failures again and resolve once more. |
| `WEBHOOK_RETENTION_FAILED` |  | Retry with backoff. |
| `WEBHOOK_RETENTION_UNAVAILABLE` |  | Retry with backoff. |
| `WEBHOOK_SIGNATURE` |  | Sign the body with the connection's current webhook secret. |
| `WEBHOOK_SNAPSHOT_UNAVAILABLE` |  | Resend the event from the source system instead of replaying. |
| `WEBHOOK_STALE_CONTEXT` |  | Resend the event from the source system. |
| `WEBHOOK_STILL_PENDING` |  | Wait for it to run before resolving it. |
| `WEBHOOK_UNAVAILABLE` |  | Retry the webhook. |
| `WEBHOOK_WORK_CHANGED` |  | Retry with backoff. |

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

## Connection with runs and metrics {#retrieve}

`GET /api/v1/connections/{id}`

Scopes: `connections:read`. SDK name: `pb.connections.retrieve`.

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

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `CONNECTION_CONFLICT` |  | Fetch it with GET /api/v1/connections/{id} and send the change again. |
| `CONNECTION_DISABLED` |  | Enable it with PATCH /api/v1/connections/{id}, then send the request again. |
| `CONNECTION_NOT_FOUND` |  | Check the id with GET /api/v1/connections. |
| `CONNECTOR_NOT_FOUND` |  | List valid types with GET /api/v1/connectors. |
| `CONNECTOR_UNKNOWN` |  | Set type to a value from GET /api/v1/connectors. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `HOLDER_EMAIL_INVALID` |  | Correct the email in the source system, then sync the connection again. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_UNSUPPORTED` |  | Create the connection in a mode the connector supports; GET /api/v1/connectors/{type} lists them. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `ORG_INACTIVE` |  | Reactivate it with POST /api/v1/orgs/{orgId}/reopen or ask the platform owner. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UNSAFE_URL` |  | Use a public https URL. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `WEBHOOK_ALREADY_FINISHED` |  | Do nothing; check its status with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_CONTEXT_CONFLICT` |  | Resend the event from the source system. |
| `WEBHOOK_DISPATCH_INCOMPLETE` |  | Retry with backoff. |
| `WEBHOOK_EFFECT_UNCERTAIN` |  | Resolve it with POST /api/v1/connections/{id}/webhook-failures/{retentionId}/resolve after checking the pass. |
| `WEBHOOK_ENQUEUE_FAILED` |  | Retry with backoff. |
| `WEBHOOK_ITEM_BUSY` |  | Retry with backoff. |
| `WEBHOOK_ITEM_PENDING` |  | Retry with backoff. |
| `WEBHOOK_NOTHING_TO_RESOLVE` |  | Do nothing; list failures with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_NOT_FOUND` |  | Check the retentionId with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_PAYLOAD` |  | Send the body in the format the connector documents. |
| `WEBHOOK_PAYLOAD_MISSING` |  | Retry with backoff; if it persists, resend the event from the source. |
| `WEBHOOK_REFERENCE_MODE` |  | Retry with backoff. |
| `WEBHOOK_REFERENCE_MODE_CHANGED` |  | Resend the event from the source system. |
| `WEBHOOK_RESOLVE_CONFLICT` |  | List failures again and resolve once more. |
| `WEBHOOK_RETENTION_FAILED` |  | Retry with backoff. |
| `WEBHOOK_RETENTION_UNAVAILABLE` |  | Retry with backoff. |
| `WEBHOOK_SIGNATURE` |  | Sign the body with the connection's current webhook secret. |
| `WEBHOOK_SNAPSHOT_UNAVAILABLE` |  | Resend the event from the source system instead of replaying. |
| `WEBHOOK_STALE_CONTEXT` |  | Resend the event from the source system. |
| `WEBHOOK_STILL_PENDING` |  | Wait for it to run before resolving it. |
| `WEBHOOK_UNAVAILABLE` |  | Retry the webhook. |
| `WEBHOOK_WORK_CHANGED` |  | Retry with backoff. |

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

## Update a connection {#update}

`PATCH /api/v1/connections/{id}`

Scopes: `connections:write`. SDK name: `pb.connections.update`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `name` | body | string · max 120 |  |  |
| `config` | body | object |  |  |
| `secrets` | body | object |  |  |
| `webhookSecret` | body | string · max 256 |  |  |
| `mapping` | body | object |  |  |
| `defaultTemplateId` | body | string · max 64 |  |  |
| `holderEmailField` | body | string · max 200 |  |  |
| `autoCreate` | body | boolean |  |  |
| `autoEmail` | body | boolean |  |  |
| `onMissing` | body | "keep" \| "flag" \| "void" |  |  |
| `voidWhen` | body | object[] |  |  |
| `mode` | body | "poll" \| "webhook" \| "hybrid" \| "manual" \| "snapshot" |  |  |
| `intervalSeconds` | body | integer · ≥ 60 |  |  |
| `maxConcurrency` | body | integer \| null · ≥ 1 · ≤ 20 |  |  |
| `requestsPerMinute` | body | integer \| null · ≥ 1 · ≤ 6000 |  |  |
| `enabled` | body | boolean |  |  |
| `overlapSeconds` | body | 0 \| 3600 \| 86400 \| 604800 |  |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `CONNECTION_CONFLICT` |  | Fetch it with GET /api/v1/connections/{id} and send the change again. |
| `CONNECTION_DISABLED` |  | Enable it with PATCH /api/v1/connections/{id}, then send the request again. |
| `CONNECTION_NOT_FOUND` |  | Check the id with GET /api/v1/connections. |
| `CONNECTOR_NOT_FOUND` |  | List valid types with GET /api/v1/connectors. |
| `CONNECTOR_UNKNOWN` |  | Set type to a value from GET /api/v1/connectors. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `HOLDER_EMAIL_INVALID` |  | Correct the email in the source system, then sync the connection again. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_UNSUPPORTED` |  | Create the connection in a mode the connector supports; GET /api/v1/connectors/{type} lists them. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `ORG_INACTIVE` |  | Reactivate it with POST /api/v1/orgs/{orgId}/reopen or ask the platform owner. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UNSAFE_URL` |  | Use a public https URL. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `WEBHOOK_ALREADY_FINISHED` |  | Do nothing; check its status with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_CONTEXT_CONFLICT` |  | Resend the event from the source system. |
| `WEBHOOK_DISPATCH_INCOMPLETE` |  | Retry with backoff. |
| `WEBHOOK_EFFECT_UNCERTAIN` |  | Resolve it with POST /api/v1/connections/{id}/webhook-failures/{retentionId}/resolve after checking the pass. |
| `WEBHOOK_ENQUEUE_FAILED` |  | Retry with backoff. |
| `WEBHOOK_ITEM_BUSY` |  | Retry with backoff. |
| `WEBHOOK_ITEM_PENDING` |  | Retry with backoff. |
| `WEBHOOK_NOTHING_TO_RESOLVE` |  | Do nothing; list failures with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_NOT_FOUND` |  | Check the retentionId with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_PAYLOAD` |  | Send the body in the format the connector documents. |
| `WEBHOOK_PAYLOAD_MISSING` |  | Retry with backoff; if it persists, resend the event from the source. |
| `WEBHOOK_REFERENCE_MODE` |  | Retry with backoff. |
| `WEBHOOK_REFERENCE_MODE_CHANGED` |  | Resend the event from the source system. |
| `WEBHOOK_RESOLVE_CONFLICT` |  | List failures again and resolve once more. |
| `WEBHOOK_RETENTION_FAILED` |  | Retry with backoff. |
| `WEBHOOK_RETENTION_UNAVAILABLE` |  | Retry with backoff. |
| `WEBHOOK_SIGNATURE` |  | Sign the body with the connection's current webhook secret. |
| `WEBHOOK_SNAPSHOT_UNAVAILABLE` |  | Resend the event from the source system instead of replaying. |
| `WEBHOOK_STALE_CONTEXT` |  | Resend the event from the source system. |
| `WEBHOOK_STILL_PENDING` |  | Wait for it to run before resolving it. |
| `WEBHOOK_UNAVAILABLE` |  | Retry the webhook. |
| `WEBHOOK_WORK_CHANGED` |  | Retry with backoff. |

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

## Delete a connection {#delete}

`DELETE /api/v1/connections/{id}`

Scopes: `connections:write`. SDK name: `pb.connections.delete`.

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

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `CONNECTION_CONFLICT` |  | Fetch it with GET /api/v1/connections/{id} and send the change again. |
| `CONNECTION_DISABLED` |  | Enable it with PATCH /api/v1/connections/{id}, then send the request again. |
| `CONNECTION_NOT_FOUND` |  | Check the id with GET /api/v1/connections. |
| `CONNECTOR_NOT_FOUND` |  | List valid types with GET /api/v1/connectors. |
| `CONNECTOR_UNKNOWN` |  | Set type to a value from GET /api/v1/connectors. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `HOLDER_EMAIL_INVALID` |  | Correct the email in the source system, then sync the connection again. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_UNSUPPORTED` |  | Create the connection in a mode the connector supports; GET /api/v1/connectors/{type} lists them. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `ORG_INACTIVE` |  | Reactivate it with POST /api/v1/orgs/{orgId}/reopen or ask the platform owner. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UNSAFE_URL` |  | Use a public https URL. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `WEBHOOK_ALREADY_FINISHED` |  | Do nothing; check its status with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_CONTEXT_CONFLICT` |  | Resend the event from the source system. |
| `WEBHOOK_DISPATCH_INCOMPLETE` |  | Retry with backoff. |
| `WEBHOOK_EFFECT_UNCERTAIN` |  | Resolve it with POST /api/v1/connections/{id}/webhook-failures/{retentionId}/resolve after checking the pass. |
| `WEBHOOK_ENQUEUE_FAILED` |  | Retry with backoff. |
| `WEBHOOK_ITEM_BUSY` |  | Retry with backoff. |
| `WEBHOOK_ITEM_PENDING` |  | Retry with backoff. |
| `WEBHOOK_NOTHING_TO_RESOLVE` |  | Do nothing; list failures with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_NOT_FOUND` |  | Check the retentionId with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_PAYLOAD` |  | Send the body in the format the connector documents. |
| `WEBHOOK_PAYLOAD_MISSING` |  | Retry with backoff; if it persists, resend the event from the source. |
| `WEBHOOK_REFERENCE_MODE` |  | Retry with backoff. |
| `WEBHOOK_REFERENCE_MODE_CHANGED` |  | Resend the event from the source system. |
| `WEBHOOK_RESOLVE_CONFLICT` |  | List failures again and resolve once more. |
| `WEBHOOK_RETENTION_FAILED` |  | Retry with backoff. |
| `WEBHOOK_RETENTION_UNAVAILABLE` |  | Retry with backoff. |
| `WEBHOOK_SIGNATURE` |  | Sign the body with the connection's current webhook secret. |
| `WEBHOOK_SNAPSHOT_UNAVAILABLE` |  | Resend the event from the source system instead of replaying. |
| `WEBHOOK_STALE_CONTEXT` |  | Resend the event from the source system. |
| `WEBHOOK_STILL_PENDING` |  | Wait for it to run before resolving it. |
| `WEBHOOK_UNAVAILABLE` |  | Retry the webhook. |
| `WEBHOOK_WORK_CHANGED` |  | Retry with backoff. |

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

## Test an unsaved configuration {#testConfig}

`POST /api/v1/connections/test-config`

Scopes: `connections:write`. SDK name: `pb.connections.testConfig`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orgId` | body | string · max 64 | yes |  |
| `connectorType` | body | string · max 64 | yes |  |
| `config` | body | object | yes |  |
| `secrets` | body | object |  |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `CONNECTION_CONFLICT` |  | Fetch it with GET /api/v1/connections/{id} and send the change again. |
| `CONNECTION_DISABLED` |  | Enable it with PATCH /api/v1/connections/{id}, then send the request again. |
| `CONNECTION_NOT_FOUND` |  | Check the id with GET /api/v1/connections. |
| `CONNECTOR_NOT_FOUND` |  | List valid types with GET /api/v1/connectors. |
| `CONNECTOR_UNKNOWN` |  | Set type to a value from GET /api/v1/connectors. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `HOLDER_EMAIL_INVALID` |  | Correct the email in the source system, then sync the connection again. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_UNSUPPORTED` |  | Create the connection in a mode the connector supports; GET /api/v1/connectors/{type} lists them. |
| `ORG_INACTIVE` |  | Reactivate it with POST /api/v1/orgs/{orgId}/reopen or ask the platform owner. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UNSAFE_URL` |  | Use a public https URL. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `WEBHOOK_ALREADY_FINISHED` |  | Do nothing; check its status with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_CONTEXT_CONFLICT` |  | Resend the event from the source system. |
| `WEBHOOK_DISPATCH_INCOMPLETE` |  | Retry with backoff. |
| `WEBHOOK_EFFECT_UNCERTAIN` |  | Resolve it with POST /api/v1/connections/{id}/webhook-failures/{retentionId}/resolve after checking the pass. |
| `WEBHOOK_ENQUEUE_FAILED` |  | Retry with backoff. |
| `WEBHOOK_ITEM_BUSY` |  | Retry with backoff. |
| `WEBHOOK_ITEM_PENDING` |  | Retry with backoff. |
| `WEBHOOK_NOTHING_TO_RESOLVE` |  | Do nothing; list failures with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_NOT_FOUND` |  | Check the retentionId with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_PAYLOAD` |  | Send the body in the format the connector documents. |
| `WEBHOOK_PAYLOAD_MISSING` |  | Retry with backoff; if it persists, resend the event from the source. |
| `WEBHOOK_REFERENCE_MODE` |  | Retry with backoff. |
| `WEBHOOK_REFERENCE_MODE_CHANGED` |  | Resend the event from the source system. |
| `WEBHOOK_RESOLVE_CONFLICT` |  | List failures again and resolve once more. |
| `WEBHOOK_RETENTION_FAILED` |  | Retry with backoff. |
| `WEBHOOK_RETENTION_UNAVAILABLE` |  | Retry with backoff. |
| `WEBHOOK_SIGNATURE` |  | Sign the body with the connection's current webhook secret. |
| `WEBHOOK_SNAPSHOT_UNAVAILABLE` |  | Resend the event from the source system instead of replaying. |
| `WEBHOOK_STALE_CONTEXT` |  | Resend the event from the source system. |
| `WEBHOOK_STILL_PENDING` |  | Wait for it to run before resolving it. |
| `WEBHOOK_UNAVAILABLE` |  | Retry the webhook. |
| `WEBHOOK_WORK_CHANGED` |  | Retry with backoff. |

```sh
curl -X POST "https://passbook.mobile/api/v1/connections/test-config" \
  -H "Authorization: Bearer $PASSBOOK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "orgId": "0193a1b2-7c00-7000-8000-0000000000a1",
  "connectorType": "Example",
  "config": {}
}'
```

## Test the connection {#test}

`POST /api/v1/connections/{id}/test`

Scopes: `connections:write`. SDK name: `pb.connections.test`.

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

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `CONNECTION_CONFLICT` |  | Fetch it with GET /api/v1/connections/{id} and send the change again. |
| `CONNECTION_DISABLED` |  | Enable it with PATCH /api/v1/connections/{id}, then send the request again. |
| `CONNECTION_NOT_FOUND` |  | Check the id with GET /api/v1/connections. |
| `CONNECTOR_NOT_FOUND` |  | List valid types with GET /api/v1/connectors. |
| `CONNECTOR_UNKNOWN` |  | Set type to a value from GET /api/v1/connectors. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `HOLDER_EMAIL_INVALID` |  | Correct the email in the source system, then sync the connection again. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_UNSUPPORTED` |  | Create the connection in a mode the connector supports; GET /api/v1/connectors/{type} lists them. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `ORG_INACTIVE` |  | Reactivate it with POST /api/v1/orgs/{orgId}/reopen or ask the platform owner. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UNSAFE_URL` |  | Use a public https URL. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `WEBHOOK_ALREADY_FINISHED` |  | Do nothing; check its status with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_CONTEXT_CONFLICT` |  | Resend the event from the source system. |
| `WEBHOOK_DISPATCH_INCOMPLETE` |  | Retry with backoff. |
| `WEBHOOK_EFFECT_UNCERTAIN` |  | Resolve it with POST /api/v1/connections/{id}/webhook-failures/{retentionId}/resolve after checking the pass. |
| `WEBHOOK_ENQUEUE_FAILED` |  | Retry with backoff. |
| `WEBHOOK_ITEM_BUSY` |  | Retry with backoff. |
| `WEBHOOK_ITEM_PENDING` |  | Retry with backoff. |
| `WEBHOOK_NOTHING_TO_RESOLVE` |  | Do nothing; list failures with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_NOT_FOUND` |  | Check the retentionId with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_PAYLOAD` |  | Send the body in the format the connector documents. |
| `WEBHOOK_PAYLOAD_MISSING` |  | Retry with backoff; if it persists, resend the event from the source. |
| `WEBHOOK_REFERENCE_MODE` |  | Retry with backoff. |
| `WEBHOOK_REFERENCE_MODE_CHANGED` |  | Resend the event from the source system. |
| `WEBHOOK_RESOLVE_CONFLICT` |  | List failures again and resolve once more. |
| `WEBHOOK_RETENTION_FAILED` |  | Retry with backoff. |
| `WEBHOOK_RETENTION_UNAVAILABLE` |  | Retry with backoff. |
| `WEBHOOK_SIGNATURE` |  | Sign the body with the connection's current webhook secret. |
| `WEBHOOK_SNAPSHOT_UNAVAILABLE` |  | Resend the event from the source system instead of replaying. |
| `WEBHOOK_STALE_CONTEXT` |  | Resend the event from the source system. |
| `WEBHOOK_STILL_PENDING` |  | Wait for it to run before resolving it. |
| `WEBHOOK_UNAVAILABLE` |  | Retry the webhook. |
| `WEBHOOK_WORK_CHANGED` |  | Retry with backoff. |

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

## Sync now {#sync}

`POST /api/v1/connections/{id}/sync`

Scopes: `connections:write`. SDK name: `pb.connections.sync`.

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

Returns `202`.

| Code | Status | Fix |
| --- | --- | --- |
| `CONNECTION_CONFLICT` |  | Fetch it with GET /api/v1/connections/{id} and send the change again. |
| `CONNECTION_DISABLED` |  | Enable it with PATCH /api/v1/connections/{id}, then send the request again. |
| `CONNECTION_NOT_FOUND` |  | Check the id with GET /api/v1/connections. |
| `CONNECTOR_NOT_FOUND` |  | List valid types with GET /api/v1/connectors. |
| `CONNECTOR_UNKNOWN` |  | Set type to a value from GET /api/v1/connectors. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `HOLDER_EMAIL_INVALID` |  | Correct the email in the source system, then sync the connection again. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_UNSUPPORTED` |  | Create the connection in a mode the connector supports; GET /api/v1/connectors/{type} lists them. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `ORG_INACTIVE` |  | Reactivate it with POST /api/v1/orgs/{orgId}/reopen or ask the platform owner. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UNSAFE_URL` |  | Use a public https URL. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `WEBHOOK_ALREADY_FINISHED` |  | Do nothing; check its status with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_CONTEXT_CONFLICT` |  | Resend the event from the source system. |
| `WEBHOOK_DISPATCH_INCOMPLETE` |  | Retry with backoff. |
| `WEBHOOK_EFFECT_UNCERTAIN` |  | Resolve it with POST /api/v1/connections/{id}/webhook-failures/{retentionId}/resolve after checking the pass. |
| `WEBHOOK_ENQUEUE_FAILED` |  | Retry with backoff. |
| `WEBHOOK_ITEM_BUSY` |  | Retry with backoff. |
| `WEBHOOK_ITEM_PENDING` |  | Retry with backoff. |
| `WEBHOOK_NOTHING_TO_RESOLVE` |  | Do nothing; list failures with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_NOT_FOUND` |  | Check the retentionId with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_PAYLOAD` |  | Send the body in the format the connector documents. |
| `WEBHOOK_PAYLOAD_MISSING` |  | Retry with backoff; if it persists, resend the event from the source. |
| `WEBHOOK_REFERENCE_MODE` |  | Retry with backoff. |
| `WEBHOOK_REFERENCE_MODE_CHANGED` |  | Resend the event from the source system. |
| `WEBHOOK_RESOLVE_CONFLICT` |  | List failures again and resolve once more. |
| `WEBHOOK_RETENTION_FAILED` |  | Retry with backoff. |
| `WEBHOOK_RETENTION_UNAVAILABLE` |  | Retry with backoff. |
| `WEBHOOK_SIGNATURE` |  | Sign the body with the connection's current webhook secret. |
| `WEBHOOK_SNAPSHOT_UNAVAILABLE` |  | Resend the event from the source system instead of replaying. |
| `WEBHOOK_STALE_CONTEXT` |  | Resend the event from the source system. |
| `WEBHOOK_STILL_PENDING` |  | Wait for it to run before resolving it. |
| `WEBHOOK_UNAVAILABLE` |  | Retry the webhook. |
| `WEBHOOK_WORK_CHANGED` |  | Retry with backoff. |

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

## Generate a new webhook secret {#rotateWebhookSecret}

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

Scopes: `connections:write`. SDK name: `pb.connections.rotateWebhookSecret`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `overlapSeconds` | query | number \| null |  |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `CONNECTION_CONFLICT` |  | Fetch it with GET /api/v1/connections/{id} and send the change again. |
| `CONNECTION_DISABLED` |  | Enable it with PATCH /api/v1/connections/{id}, then send the request again. |
| `CONNECTION_NOT_FOUND` |  | Check the id with GET /api/v1/connections. |
| `CONNECTOR_NOT_FOUND` |  | List valid types with GET /api/v1/connectors. |
| `CONNECTOR_UNKNOWN` |  | Set type to a value from GET /api/v1/connectors. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `HOLDER_EMAIL_INVALID` |  | Correct the email in the source system, then sync the connection again. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_UNSUPPORTED` |  | Create the connection in a mode the connector supports; GET /api/v1/connectors/{type} lists them. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `ORG_INACTIVE` |  | Reactivate it with POST /api/v1/orgs/{orgId}/reopen or ask the platform owner. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UNSAFE_URL` |  | Use a public https URL. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `WEBHOOK_ALREADY_FINISHED` |  | Do nothing; check its status with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_CONTEXT_CONFLICT` |  | Resend the event from the source system. |
| `WEBHOOK_DISPATCH_INCOMPLETE` |  | Retry with backoff. |
| `WEBHOOK_EFFECT_UNCERTAIN` |  | Resolve it with POST /api/v1/connections/{id}/webhook-failures/{retentionId}/resolve after checking the pass. |
| `WEBHOOK_ENQUEUE_FAILED` |  | Retry with backoff. |
| `WEBHOOK_ITEM_BUSY` |  | Retry with backoff. |
| `WEBHOOK_ITEM_PENDING` |  | Retry with backoff. |
| `WEBHOOK_NOTHING_TO_RESOLVE` |  | Do nothing; list failures with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_NOT_FOUND` |  | Check the retentionId with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_PAYLOAD` |  | Send the body in the format the connector documents. |
| `WEBHOOK_PAYLOAD_MISSING` |  | Retry with backoff; if it persists, resend the event from the source. |
| `WEBHOOK_REFERENCE_MODE` |  | Retry with backoff. |
| `WEBHOOK_REFERENCE_MODE_CHANGED` |  | Resend the event from the source system. |
| `WEBHOOK_RESOLVE_CONFLICT` |  | List failures again and resolve once more. |
| `WEBHOOK_RETENTION_FAILED` |  | Retry with backoff. |
| `WEBHOOK_RETENTION_UNAVAILABLE` |  | Retry with backoff. |
| `WEBHOOK_SIGNATURE` |  | Sign the body with the connection's current webhook secret. |
| `WEBHOOK_SNAPSHOT_UNAVAILABLE` |  | Resend the event from the source system instead of replaying. |
| `WEBHOOK_STALE_CONTEXT` |  | Resend the event from the source system. |
| `WEBHOOK_STILL_PENDING` |  | Wait for it to run before resolving it. |
| `WEBHOOK_UNAVAILABLE` |  | Retry the webhook. |
| `WEBHOOK_WORK_CHANGED` |  | Retry with backoff. |

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

## Stop accepting the previous webhook secret now {#revokePreviousWebhookSecret}

`DELETE /api/v1/connections/{id}/webhook-secret/previous`

Scopes: `connections:write`. SDK name: `pb.connections.revokePreviousWebhookSecret`.

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

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `CONNECTION_CONFLICT` |  | Fetch it with GET /api/v1/connections/{id} and send the change again. |
| `CONNECTION_DISABLED` |  | Enable it with PATCH /api/v1/connections/{id}, then send the request again. |
| `CONNECTION_NOT_FOUND` |  | Check the id with GET /api/v1/connections. |
| `CONNECTOR_NOT_FOUND` |  | List valid types with GET /api/v1/connectors. |
| `CONNECTOR_UNKNOWN` |  | Set type to a value from GET /api/v1/connectors. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `HOLDER_EMAIL_INVALID` |  | Correct the email in the source system, then sync the connection again. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_UNSUPPORTED` |  | Create the connection in a mode the connector supports; GET /api/v1/connectors/{type} lists them. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `ORG_INACTIVE` |  | Reactivate it with POST /api/v1/orgs/{orgId}/reopen or ask the platform owner. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UNSAFE_URL` |  | Use a public https URL. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `WEBHOOK_ALREADY_FINISHED` |  | Do nothing; check its status with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_CONTEXT_CONFLICT` |  | Resend the event from the source system. |
| `WEBHOOK_DISPATCH_INCOMPLETE` |  | Retry with backoff. |
| `WEBHOOK_EFFECT_UNCERTAIN` |  | Resolve it with POST /api/v1/connections/{id}/webhook-failures/{retentionId}/resolve after checking the pass. |
| `WEBHOOK_ENQUEUE_FAILED` |  | Retry with backoff. |
| `WEBHOOK_ITEM_BUSY` |  | Retry with backoff. |
| `WEBHOOK_ITEM_PENDING` |  | Retry with backoff. |
| `WEBHOOK_NOTHING_TO_RESOLVE` |  | Do nothing; list failures with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_NOT_FOUND` |  | Check the retentionId with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_PAYLOAD` |  | Send the body in the format the connector documents. |
| `WEBHOOK_PAYLOAD_MISSING` |  | Retry with backoff; if it persists, resend the event from the source. |
| `WEBHOOK_REFERENCE_MODE` |  | Retry with backoff. |
| `WEBHOOK_REFERENCE_MODE_CHANGED` |  | Resend the event from the source system. |
| `WEBHOOK_RESOLVE_CONFLICT` |  | List failures again and resolve once more. |
| `WEBHOOK_RETENTION_FAILED` |  | Retry with backoff. |
| `WEBHOOK_RETENTION_UNAVAILABLE` |  | Retry with backoff. |
| `WEBHOOK_SIGNATURE` |  | Sign the body with the connection's current webhook secret. |
| `WEBHOOK_SNAPSHOT_UNAVAILABLE` |  | Resend the event from the source system instead of replaying. |
| `WEBHOOK_STALE_CONTEXT` |  | Resend the event from the source system. |
| `WEBHOOK_STILL_PENDING` |  | Wait for it to run before resolving it. |
| `WEBHOOK_UNAVAILABLE` |  | Retry the webhook. |
| `WEBHOOK_WORK_CHANGED` |  | Retry with backoff. |

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

## List runs {#runs-list}

`GET /api/v1/connections/{id}/runs`

Scopes: `connections:read`. SDK name: `pb.connections.runs.list`.

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string · max 64 | yes |  |
| `cursor` | query | string · max 512 |  |  |
| `limit` | query | integer · ≥ 1 · ≤ 200 |  |  |

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `CONNECTION_CONFLICT` |  | Fetch it with GET /api/v1/connections/{id} and send the change again. |
| `CONNECTION_DISABLED` |  | Enable it with PATCH /api/v1/connections/{id}, then send the request again. |
| `CONNECTION_NOT_FOUND` |  | Check the id with GET /api/v1/connections. |
| `CONNECTOR_NOT_FOUND` |  | List valid types with GET /api/v1/connectors. |
| `CONNECTOR_UNKNOWN` |  | Set type to a value from GET /api/v1/connectors. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `HOLDER_EMAIL_INVALID` |  | Correct the email in the source system, then sync the connection again. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_UNSUPPORTED` |  | Create the connection in a mode the connector supports; GET /api/v1/connectors/{type} lists them. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `ORG_INACTIVE` |  | Reactivate it with POST /api/v1/orgs/{orgId}/reopen or ask the platform owner. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UNSAFE_URL` |  | Use a public https URL. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `WEBHOOK_ALREADY_FINISHED` |  | Do nothing; check its status with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_CONTEXT_CONFLICT` |  | Resend the event from the source system. |
| `WEBHOOK_DISPATCH_INCOMPLETE` |  | Retry with backoff. |
| `WEBHOOK_EFFECT_UNCERTAIN` |  | Resolve it with POST /api/v1/connections/{id}/webhook-failures/{retentionId}/resolve after checking the pass. |
| `WEBHOOK_ENQUEUE_FAILED` |  | Retry with backoff. |
| `WEBHOOK_ITEM_BUSY` |  | Retry with backoff. |
| `WEBHOOK_ITEM_PENDING` |  | Retry with backoff. |
| `WEBHOOK_NOTHING_TO_RESOLVE` |  | Do nothing; list failures with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_NOT_FOUND` |  | Check the retentionId with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_PAYLOAD` |  | Send the body in the format the connector documents. |
| `WEBHOOK_PAYLOAD_MISSING` |  | Retry with backoff; if it persists, resend the event from the source. |
| `WEBHOOK_REFERENCE_MODE` |  | Retry with backoff. |
| `WEBHOOK_REFERENCE_MODE_CHANGED` |  | Resend the event from the source system. |
| `WEBHOOK_RESOLVE_CONFLICT` |  | List failures again and resolve once more. |
| `WEBHOOK_RETENTION_FAILED` |  | Retry with backoff. |
| `WEBHOOK_RETENTION_UNAVAILABLE` |  | Retry with backoff. |
| `WEBHOOK_SIGNATURE` |  | Sign the body with the connection's current webhook secret. |
| `WEBHOOK_SNAPSHOT_UNAVAILABLE` |  | Resend the event from the source system instead of replaying. |
| `WEBHOOK_STALE_CONTEXT` |  | Resend the event from the source system. |
| `WEBHOOK_STILL_PENDING` |  | Wait for it to run before resolving it. |
| `WEBHOOK_UNAVAILABLE` |  | Retry the webhook. |
| `WEBHOOK_WORK_CHANGED` |  | Retry with backoff. |

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

## List retained webhook status {#webhookFailures-list}

`GET /api/v1/connections/{id}/webhook-failures`

Scopes: `connections:read`. SDK name: `pb.connections.webhookFailures.list`.

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

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `CONNECTION_CONFLICT` |  | Fetch it with GET /api/v1/connections/{id} and send the change again. |
| `CONNECTION_DISABLED` |  | Enable it with PATCH /api/v1/connections/{id}, then send the request again. |
| `CONNECTION_NOT_FOUND` |  | Check the id with GET /api/v1/connections. |
| `CONNECTOR_NOT_FOUND` |  | List valid types with GET /api/v1/connectors. |
| `CONNECTOR_UNKNOWN` |  | Set type to a value from GET /api/v1/connectors. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `HOLDER_EMAIL_INVALID` |  | Correct the email in the source system, then sync the connection again. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_UNSUPPORTED` |  | Create the connection in a mode the connector supports; GET /api/v1/connectors/{type} lists them. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `ORG_INACTIVE` |  | Reactivate it with POST /api/v1/orgs/{orgId}/reopen or ask the platform owner. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UNSAFE_URL` |  | Use a public https URL. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `WEBHOOK_ALREADY_FINISHED` |  | Do nothing; check its status with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_CONTEXT_CONFLICT` |  | Resend the event from the source system. |
| `WEBHOOK_DISPATCH_INCOMPLETE` |  | Retry with backoff. |
| `WEBHOOK_EFFECT_UNCERTAIN` |  | Resolve it with POST /api/v1/connections/{id}/webhook-failures/{retentionId}/resolve after checking the pass. |
| `WEBHOOK_ENQUEUE_FAILED` |  | Retry with backoff. |
| `WEBHOOK_ITEM_BUSY` |  | Retry with backoff. |
| `WEBHOOK_ITEM_PENDING` |  | Retry with backoff. |
| `WEBHOOK_NOTHING_TO_RESOLVE` |  | Do nothing; list failures with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_NOT_FOUND` |  | Check the retentionId with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_PAYLOAD` |  | Send the body in the format the connector documents. |
| `WEBHOOK_PAYLOAD_MISSING` |  | Retry with backoff; if it persists, resend the event from the source. |
| `WEBHOOK_REFERENCE_MODE` |  | Retry with backoff. |
| `WEBHOOK_REFERENCE_MODE_CHANGED` |  | Resend the event from the source system. |
| `WEBHOOK_RESOLVE_CONFLICT` |  | List failures again and resolve once more. |
| `WEBHOOK_RETENTION_FAILED` |  | Retry with backoff. |
| `WEBHOOK_RETENTION_UNAVAILABLE` |  | Retry with backoff. |
| `WEBHOOK_SIGNATURE` |  | Sign the body with the connection's current webhook secret. |
| `WEBHOOK_SNAPSHOT_UNAVAILABLE` |  | Resend the event from the source system instead of replaying. |
| `WEBHOOK_STALE_CONTEXT` |  | Resend the event from the source system. |
| `WEBHOOK_STILL_PENDING` |  | Wait for it to run before resolving it. |
| `WEBHOOK_UNAVAILABLE` |  | Retry the webhook. |
| `WEBHOOK_WORK_CHANGED` |  | Retry with backoff. |

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

## Replay a retained webhook {#webhookFailures-replay}

`POST /api/v1/connections/{id}/webhook-failures/{retentionId}/replay`

Scopes: `connections:write`. SDK name: `pb.connections.webhookFailures.replay`.

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

Returns `202`.

| Code | Status | Fix |
| --- | --- | --- |
| `CONNECTION_CONFLICT` |  | Fetch it with GET /api/v1/connections/{id} and send the change again. |
| `CONNECTION_DISABLED` |  | Enable it with PATCH /api/v1/connections/{id}, then send the request again. |
| `CONNECTION_NOT_FOUND` |  | Check the id with GET /api/v1/connections. |
| `CONNECTOR_NOT_FOUND` |  | List valid types with GET /api/v1/connectors. |
| `CONNECTOR_UNKNOWN` |  | Set type to a value from GET /api/v1/connectors. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `HOLDER_EMAIL_INVALID` |  | Correct the email in the source system, then sync the connection again. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_UNSUPPORTED` |  | Create the connection in a mode the connector supports; GET /api/v1/connectors/{type} lists them. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `ORG_INACTIVE` |  | Reactivate it with POST /api/v1/orgs/{orgId}/reopen or ask the platform owner. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UNSAFE_URL` |  | Use a public https URL. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `WEBHOOK_ALREADY_FINISHED` |  | Do nothing; check its status with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_CONTEXT_CONFLICT` |  | Resend the event from the source system. |
| `WEBHOOK_DISPATCH_INCOMPLETE` |  | Retry with backoff. |
| `WEBHOOK_EFFECT_UNCERTAIN` |  | Resolve it with POST /api/v1/connections/{id}/webhook-failures/{retentionId}/resolve after checking the pass. |
| `WEBHOOK_ENQUEUE_FAILED` |  | Retry with backoff. |
| `WEBHOOK_ITEM_BUSY` |  | Retry with backoff. |
| `WEBHOOK_ITEM_PENDING` |  | Retry with backoff. |
| `WEBHOOK_NOTHING_TO_RESOLVE` |  | Do nothing; list failures with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_NOT_FOUND` |  | Check the retentionId with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_PAYLOAD` |  | Send the body in the format the connector documents. |
| `WEBHOOK_PAYLOAD_MISSING` |  | Retry with backoff; if it persists, resend the event from the source. |
| `WEBHOOK_REFERENCE_MODE` |  | Retry with backoff. |
| `WEBHOOK_REFERENCE_MODE_CHANGED` |  | Resend the event from the source system. |
| `WEBHOOK_RESOLVE_CONFLICT` |  | List failures again and resolve once more. |
| `WEBHOOK_RETENTION_FAILED` |  | Retry with backoff. |
| `WEBHOOK_RETENTION_UNAVAILABLE` |  | Retry with backoff. |
| `WEBHOOK_SIGNATURE` |  | Sign the body with the connection's current webhook secret. |
| `WEBHOOK_SNAPSHOT_UNAVAILABLE` |  | Resend the event from the source system instead of replaying. |
| `WEBHOOK_STALE_CONTEXT` |  | Resend the event from the source system. |
| `WEBHOOK_STILL_PENDING` |  | Wait for it to run before resolving it. |
| `WEBHOOK_UNAVAILABLE` |  | Retry the webhook. |
| `WEBHOOK_WORK_CHANGED` |  | Retry with backoff. |

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

## Mark an uncertain webhook resolved after checking the source system {#webhookFailures-resolve}

`POST /api/v1/connections/{id}/webhook-failures/{retentionId}/resolve`

Scopes: `connections:write`. SDK name: `pb.connections.webhookFailures.resolve`.

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

Returns `200`.

| Code | Status | Fix |
| --- | --- | --- |
| `CONNECTION_CONFLICT` |  | Fetch it with GET /api/v1/connections/{id} and send the change again. |
| `CONNECTION_DISABLED` |  | Enable it with PATCH /api/v1/connections/{id}, then send the request again. |
| `CONNECTION_NOT_FOUND` |  | Check the id with GET /api/v1/connections. |
| `CONNECTOR_NOT_FOUND` |  | List valid types with GET /api/v1/connectors. |
| `CONNECTOR_UNKNOWN` |  | Set type to a value from GET /api/v1/connectors. |
| `CREDENTIAL_REF_KEYSET_UNAVAILABLE` |  | Retry with backoff; if it persists, send the requestId to support. |
| `FORBIDDEN` |  | Use a key with the scope the operation lists, or ask an org admin. |
| `HOLDER_EMAIL_INVALID` |  | Correct the email in the source system, then sync the connection again. |
| `INVALID_API_KEY` |  | Create a new key in the console and update PASSBOOK_KEY. |
| `MISSING_SCOPE` |  | Create a key with the scope the operation lists under security. |
| `MODE_UNSUPPORTED` |  | Create the connection in a mode the connector supports; GET /api/v1/connectors/{type} lists them. |
| `NOT_FOUND` |  | Check the id, and that the key's mode (test or live) matches the object. |
| `ORG_INACTIVE` |  | Reactivate it with POST /api/v1/orgs/{orgId}/reopen or ask the platform owner. |
| `ORG_NOT_FOUND` |  | Check orgId with GET /api/v1/orgs. |
| `PASS_CONFLICT` |  | Fetch the pass with GET /api/v1/passes/{id} and send the request again. |
| `RATE_LIMITED` |  | Wait for Retry-After seconds, then retry. Back off on repeats. |
| `TEMPLATE_NOT_FOUND` |  | Check the id with GET /api/v1/templates and the key's mode. |
| `TEMPLATE_RELEASE_CONFLICT` |  | Send the request again to use the current release. |
| `TEMPLATE_RELEASE_REQUIRED` |  | Approve a release with POST /api/v1/templates/{id}/candidates/{candidateId}/approve. |
| `UNAUTHENTICATED` |  | Send Authorization: Bearer $PASSBOOK_KEY. |
| `UNSAFE_URL` |  | Use a public https URL. |
| `VALIDATION` |  | Fix each field in issues and resend. |
| `WEBHOOK_ALREADY_FINISHED` |  | Do nothing; check its status with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_CONTEXT_CONFLICT` |  | Resend the event from the source system. |
| `WEBHOOK_DISPATCH_INCOMPLETE` |  | Retry with backoff. |
| `WEBHOOK_EFFECT_UNCERTAIN` |  | Resolve it with POST /api/v1/connections/{id}/webhook-failures/{retentionId}/resolve after checking the pass. |
| `WEBHOOK_ENQUEUE_FAILED` |  | Retry with backoff. |
| `WEBHOOK_ITEM_BUSY` |  | Retry with backoff. |
| `WEBHOOK_ITEM_PENDING` |  | Retry with backoff. |
| `WEBHOOK_NOTHING_TO_RESOLVE` |  | Do nothing; list failures with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_NOT_FOUND` |  | Check the retentionId with GET /api/v1/connections/{id}/webhook-failures. |
| `WEBHOOK_PAYLOAD` |  | Send the body in the format the connector documents. |
| `WEBHOOK_PAYLOAD_MISSING` |  | Retry with backoff; if it persists, resend the event from the source. |
| `WEBHOOK_REFERENCE_MODE` |  | Retry with backoff. |
| `WEBHOOK_REFERENCE_MODE_CHANGED` |  | Resend the event from the source system. |
| `WEBHOOK_RESOLVE_CONFLICT` |  | List failures again and resolve once more. |
| `WEBHOOK_RETENTION_FAILED` |  | Retry with backoff. |
| `WEBHOOK_RETENTION_UNAVAILABLE` |  | Retry with backoff. |
| `WEBHOOK_SIGNATURE` |  | Sign the body with the connection's current webhook secret. |
| `WEBHOOK_SNAPSHOT_UNAVAILABLE` |  | Resend the event from the source system instead of replaying. |
| `WEBHOOK_STALE_CONTEXT` |  | Resend the event from the source system. |
| `WEBHOOK_STILL_PENDING` |  | Wait for it to run before resolving it. |
| `WEBHOOK_UNAVAILABLE` |  | Retry the webhook. |
| `WEBHOOK_WORK_CHANGED` |  | Retry with backoff. |

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