Webhooks API

The Webhooks API allows you to subscribe to events happening in iTwin Platform. In simple terms, webhooks (sometimes referred to as “HTTP callbacks”) are a way for applications to communicate with one another. Webhooks are an easy way to automate workflows inside of the iTwin Platform. To use webhooks you need to create a public endpoint in order to receive webhook events. This endpoint will receive requests containing events that have been triggered by different actions throughout the iTwin Platform.

Authentication

Webhooks can only be created by a Service Application. 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.

Creation

To create a webhook, make a POST request to the create webhook endpoint. 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.

The following is a sample POST request to create an account webhook.

POST https://api.bentley.com/webhooks

{
  "callbackUrl": "https://some-callback.example.com",
  "scope": "Account",
  "secret": "4eb25d308ef2a9722ffbd7a2b7e5026f9d1f2feaca5999611d4ef8692b1ad70d",
  "eventTypes": ["iModels.iModelDeleted.v1"]
}

Activation

To activate a webhook, make a PATCH request to the update webhook endpoint with the active property set to true. By default, newly created webhooks are inactive by default and must be activated to start recieving events.

The following is a sample PATCH request to activate a webhook.

PATCH https://api.bentley.com/webhooks/{webhookId}

{
  "active": true
}

Deactivation

To deactivate a webhook, make a PATCH request to the update webhook endpoint with the active property set to false. Once deactivated, your webhook will stop receiving events.

The following is a sample PATCH request to deactivate a webhook.

PATCH https://api.bentley.com/webhooks/{webhookId}

{
  "active": false
}

Deletion

To delete a webhook, make a DELETE request to the delete webhook endpoint.

The following is a sample DELETE request to delete a webhook.

DELETE https://api.bentley.com/webhooks/{webhookId}

Events

Events are sent to the callback url of your webhooks when certain actions are triggered across the iTwin Platform. Event details will be sent in the body of the POST request to your callback url. In order to start receiving events the webhook must be active. A Signature header will be include in the POST request to validate the event came from the Webhooks V2 API. The Signature header contains a HMAC-SHA256 hash of the webhooks secret and the whole request body.

See the Events page for a detailed list of all available event types.

Event Delivery

An event is considered successfully delivered if the response from the provided callbackUrl is a 200 and has been received within the 5 seconds. The timeout of event delivery is 5 seconds. If the response is not a 200 or received past the 5 second timeout then the retry procedure is started or continued. Once the entire retry procedure completed and the event has still been failed to be delivered, the webhook is then deactivated. To reactivate a webhook, make a PATCH request to the update webhook endpoint with the active property set to true.

Event Signature Validation

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 Origin Header

Events sent to the callback url will include an Origin header in the request. This request header is set to the value https://api.bentley.com. Please ensure your CORS policies are set up correctly to allow this origin.

Event Timeout

The request to the provided callbackUrl has a timeout of 5 seconds. If a 200 response is not received in within the timeout window of 5 seconds the event delivery is considered as failed and the retry procedure is either started or continued.

Event Retry Procedure

A failed event is retried a total of 12 times over the course of 3 days. If the event has still failed to be received successfully, the webhook is then deactivated. To reactivate a webhook, make a PATCH request to the update webhook endpoint with the active property set to true.

Event Payload Example

The following is an example of the payload for a iTwins.iTwinCreated.v1 event. This event gets triggered when an iTwin is created. Event payloads will be the body of the POST request sent to the callbackUrl of the webhook. Each event type will have a different content, but the rest of the fields will always be included in the event payload. For more information on available events please refer to the Events page.

{
  "content": {
    "eventCreatedBy": "00000000-0000-0000-0000-000000000000",
    "iTwinAccountId": "00000000-0000-0000-0000-000000000000",
    "parentId": "00000000-0000-0000-0000-000000000000",
    "accountOwnerId": "00000000-0000-0000-0000-000000000000",
    "accountOwnerType": "User",
    "iTwinClass": "Endeavor",
    "iTwinSubClass": "Project"
  },
  "eventType": "iTwins.iTwinCreated.v1",
  "iTwinId": "00000000-0000-0000-0000-000000000000",
  "enqueuedDateTime": "10/12/2023 6:25:39 PM",
  "messageId": "00000000-0000-0000-0000-000000000000",
  "webhookId": "00000000-0000-0000-0000-000000000000"
}

Available Events Types

Event type are structured : api.action.version.

See the Available Events page for a detailed list of available event types.

Tutorials

Create and react to events using the Webhooks API V2

Samples

Was this page helpful?