Create webhook - Webhooks | iTwin Platform

REST API Overview

Reference

Webhooks

Download API definition:

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

Creates a new webhook. 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.

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 or in our samples.

Event Types (Required)

A list of events the webhooks will be subscribed to. See the 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. 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.

Request

Request headers

Authorization

Yes

OAuth access token with itwin-platform scope

Yes

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

Request body

Create Webhook Request

callbackUrl

String

URL where webhook events are sent.

secret

String

Optional. If none is passed one will be generated

scope

webhook-scope

scopeId

String

Required if scope is 'iTwin'. Globally unique identifier of the scope of the webhook. Not needed if Account scope is passed in. The scope id will automatically be the Account id of the calling service application

eventTypes

String[]

List of event types the webhook is subscribed to.

Example

json

{
    "callbackUrl": "https://some-callback.example.com",
    "secret": "custom-secret",
    "scope": "iTwin",
    "scopeId": "122e514a-70f1-4b34-a2b3-1935b0caca43",
    "eventTypes": [
        "iModels.iModelDeleted.v1",
        "iModels.iModelCreated.v1",
        "iModels.namedVersionCreated.v1",
        "iModels.changesReady.v1",
        "accessControl.memberAdded.v1",
        "accessControl.memberRemoved.v1",
        "accessControl.roleAssigned.v1",
        "accessControl.roleUnassigned.v1",
        "iTwins.iTwinCreated.v1",
        "iTwins.iTwinDeleted.v1",
        "synchronization.jobCompleted.v1",
        "transformations.jobCompleted.v1",
        "realityModeling.jobCompleted.v1",
        "realityAnalysis.jobCompleted.v1",
        "realityConversion.jobCompleted.v1",
        "changedElements.jobCompleted.v1"
    ]
}

Response

Response 202 Accepted

Account webhook was successfully created.

json

{
    "id": "4a1e0818-ed02-4850-9b95-6c75aeb7bbff",
    "callbackUrl": "https://some-callback.example.com",
    "secret": "custom-secret",
    "scope": "Account",
    "scopeId": "5c9d64cf-d22f-4149-ad08-c24ff395c3a0",
    "active": false,
    "eventTypes": ["iModels.iModelDeleted.v1"]
}

Response 401 Unauthorized

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.

json

{
    "error": {
        "code": "HeaderNotFound",
        "message": "Header Authorization was not found in the request. Access denied."
    }
}

Response 422 Unprocessable Entity

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

json

{
    "error": {
        "code": "InvalidCreateWebhookRequest",
        "message": "Cannot create a webhook. Make sure the request body is valid.",
        "details": [{
            "code": "InvalidRequestBody",
            "message": "Invalid request body.",
            "target": "callbackUrl"
        }]
    }
}

Response 429 Too many requests

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

json

{
    "error": {
        "code": "TooManyRequests",
        "message": "More requests were received than the subscription rate-limit allows."
    }
}

Response headers

retry-after

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

Definitions

Create Webhook Request

Webhook creation request.

callbackUrl

String

URL where webhook events are sent.

secret

String

Optional. If none is passed one will be generated

scope

webhook-scope

scopeId

String

eventTypes

String[]

List of event types the webhook is subscribed to.

Create Webhook Response

Webhook creation response.

String

Globally unique identifier of the webhook.

scopeId

String

Globally unique identifier of the scope of the webhook.

scope

webhook-scope

secret

String

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

active

Boolean

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

callbackUrl

String

URL where webhook events are sent.

eventTypes

String[]

List of event types the webhook is subscribed to.

webhook-scope

Scope of the webhook. Possible values: 'Account', 'iTwin'.

Account

String

iTwin

String

Error

Contains error information.

code

String

One of a server-defined set of error codes.

message

String

A human-readable representation of the error.

target

String, null

The target of the error.

Error Response

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.

error

Error

Error information.