> Markdown version of https://authpi.com/docs/reference/core-api/webhooks/ — fetch the complete AuthPI docs index at https://authpi.com/llms.txt to discover all available pages.

# Webhooks — AuthPI Core API

Webhook management endpoints. Webhooks deliver real-time notifications about events to your servers. Configure endpoints, authentication, and event filters.

## GET /v1/accounts/{account_id}/webhooks

**List Webhooks**

Lists all webhooks configured for an account.

Webhooks deliver real-time notifications about events to your servers. Each webhook subscription can filter which events to receive.

**Webhook statuses:**
- **active** - Receiving and delivering events
- **disabled** - Manually paused, not receiving events
- **failing** - Too many consecutive delivery failures

Use the `status` filter to find failing webhooks that may need attention.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | Optional | Maximum number of items to return (1-100, default: 50) |
| `cursor` | string | Optional | Pagination cursor (webhook ID from previous response) |
| `status` | active \| disabled \| deleted | Optional | Filter by webhook status |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Paginated list of webhooks | `object` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |

## POST /v1/accounts/{account_id}/webhooks

**Create Webhook**

Creates a new webhook subscription for an account.

Webhooks notify your servers about events in real-time via HTTP POST requests.

**Authentication options:**
- **none** - No authentication (use only for testing)
- **bearer** - Bearer token in Authorization header
- **signature** - HMAC-SHA256 signature in X-Webhook-Signature header
- **bearer+signature** - Both authentication methods

**Event filtering:**
Specify which event types to receive. Common patterns:
- Subscribe to all events: omit event_types filter
- User events only: `["user.created", "user.updated", "user.deleted"]`
- Authentication events: `["user.verification.succeeded", "user.verification.failed", "session.created"]`

**Important:** Secrets (bearer_token_plain, signature_secret_plain) are only returned once at creation. Store them securely.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |

### Request body

Content type: `application/json`

Schema: `CreateWebhookInput`

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 201 | Webhook created successfully. Secrets are only returned once - store them securely. | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 429 | **Too Many Requests** - Rate limit or resource limit exceeded. | `ApiError` |

## GET /v1/accounts/{account_id}/webhooks/{webhook_id}

**Get Webhook**

Retrieves the full configuration of a webhook by its ID.

Returns complete webhook details including:
- **Endpoint URL** - Where events are delivered
- **Event filters** - Which event types trigger deliveries
- **Authentication** - Bearer token or signature configuration (secrets not returned)
- **Status** - Active, disabled, or failing
- **Delivery statistics** - Success rate and last delivery timestamp

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `webhook_id` | string | Required | The unique identifier of the webhook |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Webhook retrieved successfully | `object` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |

## PATCH /v1/accounts/{account_id}/webhooks/{webhook_id}

**Update Webhook**

Updates a webhook's configuration.

All fields are optional - only include the fields you want to change.

**Updatable settings:**
- **url** - Change the endpoint URL
- **event_types** - Modify which events trigger deliveries
- **status** - Enable or disable the webhook
- **auth** - Change authentication method

**Authentication changes:**
If you change the auth type or request new credentials, new secrets will be generated and returned in the response. Store them immediately - they cannot be retrieved again.

**Note:** Changing the URL or auth may cause temporary delivery failures while you update your receiving server.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `webhook_id` | string | Required | The unique identifier of the webhook |

### Request body

Content type: `application/json`

Schema: `UpdateWebhook`

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Webhook updated successfully. New secrets (if generated) are only returned once. | `object` |
| 400 | **Bad Request** - The request is malformed or contains invalid data. | `ApiError` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |
| 412 | **Precondition Failed** - The resource has been modified since the provided ETag. | `PreconditionFailedError` |

## DELETE /v1/accounts/{account_id}/webhooks/{webhook_id}

**Delete Webhook**

Deletes a webhook subscription (soft delete).

The webhook is soft-deleted and stops receiving events immediately. Data is retained for 31 days before permanent deletion.

**What happens on deletion:**
- Event deliveries stop immediately
- Pending retries are cancelled
- Delivery history is retained for the grace period
- Recovery is possible by contacting support within 31 days

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `webhook_id` | string | Required | The unique identifier of the webhook |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 204 | **No Content** - The operation completed successfully with no response body. | — |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |
| 412 | **Precondition Failed** - The resource has been modified since the provided ETag. | `PreconditionFailedError` |

## GET /v1/accounts/{account_id}/webhooks/{webhook_id}/deliveries

**List Webhook Deliveries**

Lists delivery records for a webhook, newest first.

Each delivery record summarizes one event's delivery:
- **Event** - `event_id` and `event_type`
- **Status** - lifecycle `status` (pending, delivering, delivered, failing, failed), `attempt_count`, and `last_response_status`
- **Diagnostics** - `last_error` and the first/last/next attempt timestamps

Use this endpoint to:
- Debug delivery failures
- Verify your server is receiving events correctly
- Audit recent deliveries

**Retention:**
Delivery records are retained for 14 days, then automatically purged. Export anything you need for longer-term audit before then, or reconcile via the events API.

**Retry behavior:**
Failed deliveries (non-2xx response) are automatically retried with exponential backoff. The default policy makes up to 40 total attempts over roughly 28 hours, using a one-hour maximum delay between attempts. Events received while the webhook circuit breaker is open are recorded as pending and retried after the breaker reset window instead of being dropped.

### Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `account_id` | string | Required | The unique identifier of the account |
| `webhook_id` | string | Required | The unique identifier of the webhook |

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | Optional | Maximum number of items to return (1-100, default: 50) |
| `cursor` | string | Optional | Pagination cursor from the previous response's next_cursor |
| `event_type` | string | Optional | Filter by event type |
| `status` | success \| failed | Optional | Filter by outcome: success = delivered, failed = permanently failed |
| `after` | number \| null | Optional | Deliveries created after this timestamp (Unix milliseconds) |
| `before` | number \| null | Optional | Deliveries created before this timestamp (Unix milliseconds) |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Paginated list of delivery records | `object` |
| 401 | **Unauthorized** - Authentication is required or has failed. | `ApiError` |
| 403 | **Forbidden** - You don't have permission to perform this action. | `ApiError` |
| 404 | **Not Found** - The requested resource does not exist. | `ApiError` |