Create a webhook subscription
Registers a new webhook endpoint to receive events.
The signing_secret is returned ONLY in this response — store it securely. If not provided in the request, the server generates a cryptographically random secret.
TENANT SCOPING: - Provide tenant_id in query to scope the subscription to a specific tenant. - Omit tenant_id to create a system-wide subscription (receives events from all tenants). - System-wide subscriptions still respect scope_filter if provided.
EVENTS (document revision 0.1.25.33): - On success, server MUST emit one webhook.created Event.
Payload conforms to EventDataWebhookLifecycle with
new_status = ACTIVE and previous_status omitted.
correlation_id = webhook_create:<subscription_id>.
AUTHORIZATION: - Requires admin key (X-Admin-API-Key)
Authorizations
Administrative API key with full system access. Also accepted as an alternative to ApiKeyAuth on an explicit per-operation allowlist — the authoritative list is the union of operations whose security: block declares AdminKeyAuth (consult per-operation security blocks rather than this prose, which has historically drifted as the dual-auth surface expanded). When using AdminKeyAuth on list or fund endpoints, a tenant scoping parameter (typically tenant or tenant_id) is required for scoping (400 if missing) — the per-operation description specifies which. Lookup-style endpoints that uniquely identify a resource by non-tenant key (e.g. GET /v1/admin/budgets/lookup, where the (scope, unit) pair is unique) do NOT require a tenant parameter. Allowlisting is per-operation (exact method:path matching — no prefix matching, no wildcards) so new endpoints do not accidentally inherit admin-accessible status.
Parameters
Query Parameters
Scope subscription to a specific tenant. Omit for system-wide.
Request Body
Responses
Subscription created