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

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.