Webhooks API

The Webhooks API allows you to subscribe to events happening in iTwin Platform. In simple terms, webhooks, sometimes called “HTTP callbacks” are a way for apps to communicate with one another that removes any manual effort out of the equation.

Webhook

To use webhooks you need to create an API in order to receive webhook events. You will need to provide a public API endpoint called callbackUrl where you want to receive the events after you create your own webhook. Also it is required to provide a list of event types that you are interested in. After you create a webhook, it will take several seconds to get the webhook ready.

Deactivation

An existing webhook can be deactivated to temporarily stop sending events until you activate it back again. This way you don't have to delete the webhook and create a new one later.

Expiration

Webhooks have expiration time and when that time comes, webhook becomes deactivated. Before creating a webhook, you can set the expiration time to the one you want. If the expiration time was not set, webhook will expire in 30 days by default.

Security

Webhook secret

On webhook creation, webhook secret is being generated and sent back to the client.

{
  "webhook": {
    "id": "72a10fad-103d-4e23-9a43-a4ddf2ef61cc",
    "secret": "4eb25d308ef2a9722ffbd7a2b7e5026f9d1f2feaca5999611d4ef8692b1ad70d"
  }
}

Before forwarding an event to client, webhook secret is used together with whole request body to generate HMAC-SHA256 signature which is included in Signature request header. Before doing anything with the received event client 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, event SHOULD be accepted as authorized one and ignored otherwise.

Webhook event signature

Webhook signature example: sha256=a24a2e58912f4708f21eb043def1b1bcc0684b81a2e3feebe04ca558ff9830ce. The first part of the signature (before the equation sign) indicates the algorithm and the second part is generated hash which client MUST attempt to match.

Callback validation

After webhook is created, an automatic HTTP OPTIONS validation request is sent to the callback URL. This request includes WebHook-Request-Origin header which contains the origin of the sending system. The client must reply including Webhook-Allowed-Origin header in the response with the same value supplied in the Webhook-Request-Origin header, or a singular asterisk character ('*'), indicating that the delivery target supports notifications from all origins. The OPTIONS response SHOULD include the Allow header indicating the POST method being permitted.

If the client does not support the handshake described here, webhook callback can still be validated manually but not later than 2 days after creation. Initial validation request includes Webhook-Request-Callback header which contains the URL that can be called manually via HTTP GET request. If callback URL does not get validated after 2 days webhook is automatically deleted.

Supported events

iModels

iModelDeletedEvent - is triggered when related iModel is deleted.
NamedVersionCreatedEvent - is triggered when there is a new named version created for related iModel.
ChangesetPushedEvent - is triggered when there is a new changeset pushed for related iModel.
ChangesetGroupCompletedEvent - is triggered when a changeset group is closed with state "Completed".
ChangesReadyEvent - is triggered when there are new changes to the iModel which are ready to be processed.