Skip to main content
POST
Register a realm webhook
It is an upsert: registering a URL that already exists adds the new events to it (an event it already has is re-activated) and replaces its headers when the request carries them. Nothing is ever duplicated or deleted. Only realm admins can call this. Answers the webhook with every event it is now subscribed to.

Path Parameters

realmId
string<uuid>
required

ID of your realm.

Format: UUID

Body

application/json
url
string<uri>
required

Absolute HTTPS URL the events are POSTed to. The same URL registered twice is one webhook — registering it again adds events and replaces the headers.

Example:

"https://hooks.example.com/p3"

events
object[]
required

The events to subscribe the URL to. A realm-wide webhook receives them for every organization of the realm. An event the URL already has is re-activated.

Required array length: 1 - 100 elements
headers
object

Headers to send on every delivery, e.g. an authorization token. When omitted, the headers already registered for the URL are kept.


Example: {"Authorization":"Bearer …"}

Example:

Response

Successful response

A webhook: one URL that receives events, with the headers sent on every delivery.

id
string<uuid>
required

ID of the webhook. It is derived from the URL and the organization, so registering the same URL again returns the same webhook instead of a second one.

Example:

"3c9d8e7f-6a5b-5c4d-8e3f-2a1b0c9d8e7f"

realmId
string<uuid>
required

ID of the realm the webhook belongs to.

Example:

"f495ff0c-ab54-4f99-8e92-ca8682e4de9b"

organizationId
string
required

ID of the organization the webhook belongs to, or * for a realm-wide webhook, which receives the events of every organization of the realm.

Example:

"*"

url
string
required

The URL every event is POSTed to.

Example:

"https://hooks.example.com/p3"

headers
object
required

Headers sent on every delivery, as registered.


Example: {"Authorization":"Bearer …"}

Example:
events
object[]
required

Every event the webhook is subscribed to, with its status. Sorted by event name.

createdAt
string

When the webhook was registered.

Example:

"2026-10-01T09:30:00.000Z"

updatedAt
string

When the webhook was last changed.

Example:

"2026-10-02T14:03:11.000Z"