Skip to main content
POST
Create a webhook endpoint

Authorizations

Authorization
string
header
required

Your secret key: sk_test_… on the sandbox host, sk_live_… on live. A key on the wrong host gets a 401 wrong_environment. Keys are secret. Keep them on your server, never in a browser or app.

Headers

Idempotency-Key
string

Optional. Makes a retry safe, as on money-moving creates.

Maximum string length: 255

Body

application/json
url
string
required

https:// only, on a public host (no IP address, no private or internal name). Not already used by another of your endpoints.

Maximum string length: 2048
Example:

"https://acme.com/webhooks/infinity"

events
string[]
required

Event types, or exactly ["*"] for every type.

Required array length: 1 - 24 elements
Example:
description
string
Maximum string length: 500
Example:

"Production payouts"

Response

The new endpoint, with its secret.

id
string
required
Example:

"webhook_qjvv94gq6e73azsa"

url
string
required
Example:

"https://acme.com/webhooks/infinity"

events
string[]
required

Event types, or ["*"] for every type, including ones added later.

Example:
status
enum<string>
required
Available options:
enabled,
disabled
description
string | null
required
Example:

"Production payouts"

secret
string | null
required

whsec_…, for checking signatures. Only in the create response; null everywhere else.

Example:

"whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"

created_at
string<date-time>
required
Example:

"2026-10-26T10:00:00Z"

updated_at
string<date-time>
required
Example:

"2026-10-26T10:00:00Z"