The Webhooks API allows you to subscribe to events happening in iTwin Platform.

### Supported event sources

- iModels events


webhooks-v2

Webhooks API version 2 is available in General Availability.

Added technology preview operation 'Create webhook'.

Added technology preview operation 'Delete webhook'.

Added technology preview operation 'Get webhook'.

Added technology preview operation 'Get webhooks'.

Added technology preview operation 'Update webhook'.

Added event 'iModels.iModelDeleted.v1'

Added event 'iModels.iModelCreated.v1'

Added event 'iModels.namedVersionCreated.v1'

Added event 'iModels.changesReady.v1'

Added event 'accessControl.memberAdded.v1'

Added event 'accessControl.memberRemoved.v1'

Added event 'accessControl.roleAssigned.v1'

Added event 'accessControl.roleUnassigned.v1'

Added event 'iTwins.iTwinCreated.v1'

Added event 'iTwins.iTwinDeleted.v1'

Added event 'synchronization.jobCompleted.v1'

Added event 'transformations.jobCompleted.v1'

Removed operation 'Activate a webhook'.

Removed operation 'Confirm webhook callback ownership'.

Removed operation 'Create iModel events webhook'.

Removed operation 'Deactivate a webhook'.

Removed operation 'Delete a webhook'.

Removed operation 'Get a list of user webhooks'.

Removed operation 'Get the details for a webhook'.

Removed event 'iModelDeletedEvent'

Removed event 'NamedVersionCreatedEvent'

Removed event 'ChangesetPushedEvent'

Removed event 'ChangesetGroupCompletedEvent'

Removed event 'ChangesReadyEvent'

Webhooks API version 2 is available in Technical Preview. This update adds support for webhooks on the Account scope. We have also added support for events triggered by the Access Control, iTwins, iModel, Synchronization, and Transformations APIs.

Added event 'realityModeling.jobCompleted.v1'

Added event 'realityAnalysis.jobCompleted.v1'

Added event 'realityConversion.jobCompleted.v11'

Added event 'changedElements.jobCompleted.v1'

Webhooks API version 2 is available in Technical Preview. This update adds support for webhooks on the Account scope. We have also added support for events triggered by the Access Control, iTwins, iModel, Synchronization, and Transformaion APIs.

webhooks

webhooks-apis-pipeline

webhooks-create-api-status-container

webhooks-platform-health-v2

Creates a new webhook. On creation, webhook are inactive by default. To start receiving event, make a request to the [update webhook endpoint](/apis/webhooks-v2/operations/update-webhook/) 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](/tutorials/create-and-react-to-events-using-webhooks-v2/#23-add-event-authorization) or in our [samples](/apis/webhooks-v2/samples/).

#### Event Types (Required)

A list of events the webhooks will be subscribed to. See the [Events](/apis/webhooks-v2/available-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](https://developer.bentley.com/tutorials/authorize-service/). A list of your Service Applications can be found [here](https://developer.bentley.com/my-apps).

#### 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](https://bentleysystems.service-now.com/community?id=kb_article_view&sys_kb_id=1e5410491b7d8a90f3fc5287624bcb57) wiki page.


create-webhook

OAuth access token with `itwin-platform` scope

Authorization

Setting to `application/vnd.bentley.itwin-platform.v2+json` is recommended.

Accept

default

Account webhook was successfully created.

This response indicates that request lacks valid authentication credentials. Access token might not been provided, issued by the wrong issuer, does not have required scopes or request headers were malformed.

HeaderNotFound

InvalidAuthorizationScheme

InvalidHeaderValue

RequiredScopeMissing

Unauthorized

InvalidApplicationTier

Invalid request to update an account webhook. Make sure request had required properties and does not pass in readonly properties.

This response indicates that the user has sent too many requests in a given amount of time.

The number of requests exceeds the rate-limit for the client subscription.

retry-after

Delete the specified webhook. Once deleted, your webhook will stop receiving events.

#### Authentication

The Webhooks API V2 can only be called by Service Applications. 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](https://developer.bentley.com/tutorials/authorize-service/). A list of your Service Applications can be found [here](https://developer.bentley.com/my-apps).

#### 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](https://bentleysystems.service-now.com/community?id=kb_article_view&sys_kb_id=1e5410491b7d8a90f3fc5287624bcb57) wiki page.


delete-webhook

webhookId

Specified account webhooks was successfully deleted.

Retrieves the specified webhook.

#### Authentication

The Webhooks API V2 can only be called by Service Applications. This request requires an `Authorization` header with a valid Bearer token with the `webhooks:read` scope. For more information on Service Applications and how to obtain an access token can be found [here](https://developer.bentley.com/tutorials/authorize-service/). A list of your Service Applications can be found [here](https://developer.bentley.com/my-apps).

#### 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](https://bentleysystems.service-now.com/community?id=kb_article_view&sys_kb_id=1e5410491b7d8a90f3fc5287624bcb57) wiki page.


get-webhook

Retrieves a list of all webhooks that have been created by the calling user.

#### Authentication

The Webhooks API V2 can only be called by Service Applications. This request requires an `Authorization` header with a valid Bearer token with the `webhooks:read` scope. For more information on Service Applications and how to obtain an access token can be found [here](https://developer.bentley.com/tutorials/authorize-service/). A list of your Service Applications can be found [here](https://developer.bentley.com/my-apps).

#### 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](https://bentleysystems.service-now.com/community?id=kb_article_view&sys_kb_id=1e5410491b7d8a90f3fc5287624bcb57) wiki page.


get-webhooks

Updates the specified webhook.

#### Activation

To activate a webhook, make a PATCH request 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.

```http
PATCH https://api.bentley.com/webhooks/{webhookId}

{
  "active": true
}
```

#### Deactivation

To deactivate a webhook, make a PATCH request 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.

```http
PATCH https://api.bentley.com/webhooks/{webhookId}

{
  "active": false
}
```

#### Authentication

The Webhooks API V2 can only be called by Service Applications. 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](https://developer.bentley.com/tutorials/authorize-service/). A list of your Service Applications can be found [here](https://developer.bentley.com/my-apps).

#### 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](https://bentleysystems.service-now.com/community?id=kb_article_view&sys_kb_id=1e5410491b7d8a90f3fc5287624bcb57) wiki page.


update-webhook

Invalid request to create new account webhook. Make sure request had required properties and does not pass in readonly properties.

Changelog - Webhooks | iTwin Platform

This tutorial will teach you how to use Webhooks API V2 to subscribe to events and introduce basic event handling workflows.

Create and react to events using Webhooks API V2

This tutorial will teach you how to use Webhooks API V1 to subscribe to iModel events and introduce basic event handling workflows.

Changelog

Apr 25, 2024

Feb 20, 2024

Oct 12, 2023