Creates a new webhook. On creation, webhook are inactive by default. To start receiving event, make a request to the update webhook endpoint with the active
property set to true
.
Callback Url (Required)
The URL of the public endpoint all events will be sent to. HTTPS
is required for this URL. This endpoint will receive requests containing events that have been triggered by different actions throughout the iTwin Platform. A POST request will be sent to this url when an event is triggered with event details in the body of the POST request.
Scope (Required)
The scope
property is required. Currently, there are two accepted value for scope
: Account
, iTwin
.
All webhooks that are created with the Account
scope are scoped to the account of the Service Application that created it. This means all events types the webhooks is subscribed to that happen inside that account will be sent to the webhook. Please be aware that Service Application's accounts are separate from the user's account that created the Service Application.
If the webhoook is created with the iTwin
scope, then the property scopeId
is required. iTwin
scoped Webhooks will receive events for anything that is created directly inside of that iTwin
.
Secret (Optional)
The secret
property is optional. If no secret is provided in the request a secret is generated and sent back in the response. If provided, the secret must be at least 32 characters.
Before forwarding an event to the client, the webhook secret is used together with the whole request body to generate a HMAC-SHA256
signature which is included in the Signature
request header. Before doing anything with the received event the callback endpoint should handle the authorization process by using its own webhook secret copy together with request body and generate another signature on their end to validate the event source. If both signatures are the same, the event should be accepted as authorized. If the signatures do not match the event should be ignored. An example of this workflow can be found in our tutorial or in our samples.
Event Types (Required)
A list of events the webhooks will be subscribed to. See the Events page for a detailed list of all available event types.
Authentication
Webhooks can only be created by a Service Application. This request requires an Authorization
header with a valid Bearer token with the webhooks:modify
scope. For more information on Service Applications and how to obtain an access token can be found here. A list of your Service Applications can be found here.
Authorization
The Service Application must have the webhooks_maintainer
permission assigned at the iTwin level or be an Organization Administrator for the Organization that owns a given iTwin.
An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities Licensing, Cloud, and Web Services wiki page.