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 - Manually paused, not receiving events
• failing - Too many consecutive delivery failures

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

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.