Webhooks — Core API

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 - Paused manually or by AuthPI after persistent delivery failures
• deleted - Soft-deleted and awaiting retention cleanup

Use the status filter with disabled to find paused webhooks. Disabled list items include status_reason and status_by when available.

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.

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

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.

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

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.

Re-drives all permanently failed deliveries in a time window through the automatic retry schedule.

Use this to recover after an endpoint outage: once your server is healthy again, one call re-queues everything that failed while it was down. Deliveries are matched by their creation time (since ≤ created_at < before).

Behavior:

• Redelivery is asynchronous — this endpoint returns 202 with the number of deliveries scheduled; watch the deliveries list for outcomes.
• Each delivery gets a small fresh retry budget with the first re-attempt scheduled immediately and subsequent ones following the webhook's backoff.
• Up to 500 deliveries are scheduled per call, oldest first. When has_more is true, call again with the same window to continue — already-scheduled deliveries are no longer failed, so repeated calls make progress.

For replaying a single delivery (including an already-delivered one), use POST .../deliveries/{delivery_id}/redeliver instead.

Manually re-attempts a single webhook delivery (one-shot).

Use this to replay a delivery after fixing your endpoint, or to resend an event your server received but lost. The stored event payload is re-sent through the normal delivery path with a fresh signature timestamp, and the attempt is logged with source manual.

Eligible deliveries:

• failed — retries exhausted or dropped; a successful redelivery moves it to delivered
• delivered — resend of an already-delivered event; the record stays delivered even if the resend fails (the failure is visible in the attempt log)

Deliveries that are still in flight (pending, delivering, failing) return 409 — the automatic retry schedule owns them.

Behavior notes:

• The result is returned synchronously: check data.success for the outcome of this attempt. A failed redelivery does not schedule automatic retries — call this endpoint again, or use the bulk redeliver endpoint.
• The circuit breaker is bypassed for the attempt (an explicit replay is the natural probe of a recovered endpoint), but the outcome still counts toward breaker state.

To re-drive many failed deliveries after an outage, use POST /webhooks/{webhook_id}/redeliver instead.