link

href

string

Link

response-create-webhook

Globally unique identifier of the webhook.

webhook.id

Random unique secret string that will be used to compute an HMAC digest for authorized content distribution.

webhook.secret

Create Webhook Response

webhook-details

An indicator showing webhook activity. If true, webhook is actively forwarding the events. If false, webhook events are stopped.

isActive

boolean

A value that indicates if webhook callback ownership is validated.

isValidated

callbackUrl

expirationDateTime

Describes current webhook callback validation state.

validationState

_links

iModel Events Webhook Links

object

Webhook Details

Additional properties of webhook activation.

request-activate-webhook

Webhook expiration date and time. If not provided will default to 30 days after the request time.

Activate Webhook

request-create-webhook-imodel

imodelId

eventTypes

A secret string that is used for event signature validation. Will be auto-generated if not provided.

secret

Create Webhook (iModel events)

Common property representation of a webhook.

webhook

eventSource

Webhook

Contains basic event information and details.

imodel-event

content

changeset-pushed-event

imodel-deleted-event

named-version-created-event

changeset-group-completed-event

changes-ready-event

contentType

enqueuedDateTime

messageId

subscriptionId

iModel Event

Event that gets triggered when new Changeset is pushed for the iModel.

briefcaseId

Changeset id is a 40 characters SHA1 hash that is used to validate Changeset. The id of Changeset is generated from the id of its parent as well as its contents.

changesetId

Index of the Changeset (increasing, but not necessarily sequential).

changesetIndex

Globally Unique Identifier of the iModel.

Globally Unique Identifier of the project that iModel belongs to.

projectId

Changeset Pushed Event

Event that gets triggered when the iModel is deleted.

iModel Deleted Event

Event that gets triggered when new Named Version is created for the iModel.

Globally Unique Identifier of the Named Version.

versionId

Named Version Created Event

Event that gets triggered when Changeset Group is closed with state "Completed".

 Globally Unique Identifier of the closed Changeset Group

changesetGroupId

Changeset Group Completed Event

Event that gets triggered when there are new changes to the iModel which are ready to be processed.

Changes Ready Event

Contains error information and an array of more specific errors.

DetailedError

One of a server-defined set of error codes.

code

A human-readable representation of the error.

message

target

details

Error

Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.

DetailedErrorResponse

error

Detailed Error Response

ErrorResponse

Error Response

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


webhooks

webhooks-v2

---

This operation can be used to activate a deactivated webhook. Deactivated webhooks do not forward any events to the callback, activating enables this feature back again.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `webhooks:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---


activate-webhook

OAuth access token with scope `webhooks:modify`

Authorization

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

Accept

The request has been accepted for processing.

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.

application/json;InvalidAuthorizationScheme

User is not authorized to activate a webhook.

The 422 (Unprocessable Entity) status code indicates that the request cannot be processed by the server due to a client error (e.g. malformed request syntax).

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

---

### Event Types

Currently supported webhook event types:
- iModelDeletedEvent
- NamedVersionCreatedEvent
- ChangeSetPushedEvent
- ChangesetGroupCompletedEvent
- ChangesReadyEvent

### Security

On webhook creation, webhook secret is being generated. Before forwarding an event to client, secret is used together with whole event body to generate `HMAC-SHA256` signature which is included in `Signature` request header. Before doing anything with the received event client SHOULD use its own secret copy together with the event body and generate another signature on their end to validate the event source. If both signatures are the same, event SHOULD be accepted as valid one and ignored otherwise.

### Expiration

When creating a webhook expiration date time CAN be specified after which the webhook will become deactivated. If expiration time is not specified, webhook expires automatically after 30 days.

### Notes

Webhook deletion is not persisted after iModel deletion. When deleting an iModel make sure to delete related webhooks as well.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `webhooks:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---


create-imodels-webhook

Location

---

This operation can be used to deactivate a webhook. Deactivated webhooks do not forward any events to the callback. Deactivated webhooks are not deleted and can be activated again.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `webhooks:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---


deactivate-webhook

User is not authorized to deactivate a webhook.

---

Deleted webhooks can not be restored and have to be created again. If you want to temporary stop receiving events consider deactivating a webhook instead.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `webhooks:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---


delete-webhook

User is not authorized to delete a webhook.

---

Returns a list of user's owned webhooks of any event source.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `webhooks:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---


get-webhooks

OAuth access token with scope `webhooks:read`

---

Returns a detailed response of a webhook.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `webhooks:read`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---


get-webhook

---

This operation can be used to manually confirm webhook callback ownership if a client application does not support required handshake. Fully constructed URL with required query parameters values for this operation can be found within automatic validation request header `WebHook-Request-Callback` that is sent to specified callback URL after webhook is created. If webhook callback ownership was confirmed automatically, this operation should not be used anymore.

### Authentication

Requires `Authorization` header with valid Bearer token for scope `webhooks:modify`.

For more documentation on authorization and how to get access token visit [OAUTH2 Authorization](https://developer.bentley.com/apis/overview/authorization/) page.

---


confirm-webhook-callback-ownership

Webhook callback ownership was confirmed.

Events - Webhooks | iTwin Platform

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