Skip to main content
POST
Register an organization 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. Answers the webhook with every event it is now subscribed to.

Path Parameters

realmId
string<uuid>
required

ID of your realm.

Format: UUID

organizationId
string<uuid>
required

ID of the organization the webhook belongs to.

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. 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:

"c4bd3f21-dfbd-44e8-8055-68ba15bed410"

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"