Sign in

a84d4905fdbb

latestOpenAPI 3.1.02026-08-143874115.7 MB
Webhooks

Create Webhook

Creates a webhook endpoint that receives event notifications via HTTP POST.

post/webhooks

Headers

Idempotency-Keystring
Example:d9105228-4a08-46b1-8b91-42fed586d383

A unique key that makes this request safe to retry. See Idempotent requests.

Request body

api_version_datestring nullable

The dated API version (Api-Version-Date) to pin this webhook's payloads to. Omit to leave the webhook unpinned, tracking the current payload shape.

child_resource_eventsboolean

Whether to send events for child resources. For example, if the webhook is created for an account, enabling this sends events only from its connected accounts.

enabledboolean

Whether or not the webhook is enabled. Defaults to true.

eventsstring[]

The events to send the webhook for, in dot form (for example payment.succeeded).

resource_idstring nullable

The account or app to create the webhook for. Defaults to the current account.

urlstring required

The URL to send the webhook to.

Example request

{
  "api_version_date": "2026-01-01",
  "child_resource_events": true,
  "enabled": true,
  "events": [
    "payment.succeeded"
  ],
  "resource_id": "biz_xxxxxxxxxxxxxx",
  "url": "https://example.com/hooks"
}

Response

webhook created

api_version'v1' | 'v2' | 'v5' required

The API version used to format payloads sent to this webhook endpoint.

api_version_datestring nullable required

The dated API version (Api-Version-Date) that v1 payloads for this endpoint are pinned to: events serialize exactly like a REST read at this version (the native serializer where the resource has one). Null when unpinned — legacy (v2/v5) webhooks, and v1 webhooks on the legacy payload shape.

child_resource_eventsboolean required

Whether events are sent for child resources. For example, if the webhook is on an account, enabling this sends events only from its connected accounts.

consecutive_failuresinteger required

Number of consecutive deliveries whose first attempt to this endpoint failed since it last accepted one. Later retries of the same delivery do not increment it. Resets to 0 when a delivery succeeds or the webhook is re-enabled.

created_atstring required

When the webhook was created, as an ISO 8601 timestamp.

disabled_atstring nullable required

When Whop automatically disabled this webhook, as an ISO 8601 timestamp. null unless the webhook was disabled by Whop; a webhook you disabled yourself has enabled: false and a null disabled_at.

disabled_reason'delivery_failures' | 'null' nullable required

Why Whop disabled this webhook. delivery_failures means every delivery failed for 3 days straight. null when disabled_at is null.

enabledboolean required

Whether this webhook endpoint is currently active and receiving events.

eventsstring[] required
failing_sincestring nullable required

When the current failure streak began, as an ISO 8601 timestamp. Unlike last_failure_at, this is set on the streak's first failed attempt, so it shows an endpoint that is failing right now. null when the endpoint is healthy.

idstring required

Webhook ID, prefixed hook_.

last_failure_atstring nullable required

When a delivery to this endpoint most recently failed after exhausting retries, as an ISO 8601 timestamp. null if no delivery has ever failed.

resource_idstring required

ID of the resource (account or app) this webhook is attached to.

testable_eventsstring[] required
urlstring required

Destination URL where webhook payloads are delivered via HTTP POST.

webhook_secretstring nullable required

Secret key used to sign webhook payloads for verification. Include this in your HMAC validation logic. Returned on the create response and to interactive dashboard sessions; null for API-key and OAuth callers on later reads.

Example response

{
  "api_version": "v1",
  "api_version_date": "2026-01-01",
  "consecutive_failures": 9,
  "created_at": "2026-01-01T12:00:00.000Z",
  "disabled_at": "2026-01-01T12:00:00.000Z",
  "disabled_reason": "delivery_failures",
  "events": [
    "payment.succeeded"
  ],
  "failing_since": "2026-01-01T12:00:00.000Z",
  "id": "hook_xxxxxxxxxxxxxx",
  "last_failure_at": "2026-01-01T12:00:00.000Z",
  "resource_id": "biz_xxxxxxxxxxxxxx",
  "testable_events": [
    "invoice.created"
  ],
  "url": "https://example.com/hooks",
  "webhook_secret": "ws_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}