Create a webhook subscription

Creates a subscription and returns the signing secret exactly once. The url must be HTTPS and pass the subscriber URL security policy. Delivery is pull-based for recovery; there is no retry/replay endpoint. Idempotency-Key is required. Secret bytes are never response-cached: a same-key/same-body replay returns 409 ResourceConflict with the created subscription in Location. If the original secret response was lost, rotate that subscription with a new key and immediate: true. Each subscription selects exactly one ownership scope. Organization and every Account scope inside it share one 100-subscription quota; standalone root Account trees and Persons each have their own 100-subscription partition. This bounds each subject variant to 100 targets. Multi-party occurrences have at most two variants and acceptance coalesces (occurrenceId, subscriptionId), so the hard aggregate is 200 distinct targets without double-notifying an overlapping subscription. There is no configurable per-subscription delivery-rate tier. Subscription management requires platform.webhook:write on the selected scope; Organization equality/membership is insufficient, and Person scope is self-only.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
uri
required

HTTPS only. Userinfo and private, reserved, link-local, loopback, metadata, encoded-IP, or mixed public/private DNS destinations are rejected at save time and before every POST.

subscribedEvents
array of strings, unique
required
length between 1 and 500

Exact (Invoice.Paid), prefix-wildcard (Invoice.*), or global (*). Admission requires at least one catalog event whose allowed routing-subject type intersects the selected scope; Organization with shouldIncludeAccounts: true may also intersect Account events. Future wildcard matches remain subject to both this type gate and the PublicReferenceV1 complete-envelope security gate; wider classes require explicit update.

subscribedEvents*
scope
required

Explicit subject scope shared by subscriptions and the event log. Types never imply one another: Organization scope never includes Persons, Person scope never infers Accounts, and Account scope never grants sibling or Organization access.

string
metadata
object

Free-form key-value pairs. Max 50 keys; key length at most 40 characters; value length at most 500 characters. Where a list endpoint declares metadata filtering, it uses the QueryQL namespace via filter[metadata.{key}][eq]=value or filter[metadata.{key}][in][]=value. Endpoints that do not declare the dynamic Metadata filter do not support Metadata filtering.

Headers
string
required
length between 1 and 255
^[\x21-\x7e]{1,255}$

REQUIRED idempotency token for money-moving requests (e.g. transfers). The token is used by the API so a retry after a 5xx/timeout replays the original result instead of moving funds twice. Reuse the same key to retry safely; use a NEW key to issue a genuinely new transfer. Use 1-255 printable ASCII characters.

string
enum
Defaults to application/json

Generated from available response content types

Allowed:
Responses

Language
Credentials
Bearer
JWT
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json
application/problem+json