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 headers
OAuth access token with itwin-platform scope
Setting to application/vnd.bentley.itwin-platform.v2+json is recommended.
Request body
Create Webhook Request
URL where webhook events are sent.
Optional. If none is passed one will be generated
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
List of event types the webhook is subscribed to.
Example
{ "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 202 Accepted
Account webhook was successfully created.
{ "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.
{ "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.
{ "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 client sent more requests than allowed by this API for the current tier of the client.
{ "error": { "code": "RateLimitExceeded", "message": "The client sent more requests than allowed by this API for the current tier of the client." } }
Response headers
Number of seconds to wait until client is allowed to make more requests.
Create Webhook Request
Webhook creation request.
URL where webhook events are sent.
Optional. If none is passed one will be generated
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
List of event types the webhook is subscribed to.
{ "type": "object", "title": "Create Webhook Request", "description": "Webhook creation request.", "properties": { "callbackUrl": { "type": "string", "description": "URL where webhook events are sent." }, "secret": { "type": "string", "description": "Optional. If none is passed one will be generated" }, "scope": { "$ref": "#/components/schemas/webhook-scope" }, "scopeId": { "type": "string", "description": "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": { "type": "array", "description": "List of event types the webhook is subscribed to.", "items": { "type": "string" } } }, "additionalProperties": false }
Create Webhook Response
Webhook creation response.
Globally unique identifier of the webhook.
Globally unique identifier of the scope of the webhook.
Random unique secret string that will be used to compute an HMAC digest for authorized content distribution.
An indicator showing webhook activity. If true, webhook is actively forwarding the events. If false, webhook events are stopped.
URL where webhook events are sent.
List of event types the webhook is subscribed to.
{ "type": "object", "title": "Create Webhook Response", "description": "Webhook creation response.", "properties": { "id": { "type": "string", "description": "Globally unique identifier of the webhook." }, "scopeId": { "type": "string", "description": "Globally unique identifier of the scope of the webhook." }, "scope": { "$ref": "#/components/schemas/webhook-scope" }, "secret": { "type": "string", "description": "Random unique secret string that will be used to compute an HMAC digest for authorized content distribution." }, "active": { "type": "boolean", "description": "An indicator showing webhook activity. If true, webhook is actively forwarding the events. If false, webhook events are stopped." }, "callbackUrl": { "type": "string", "description": "URL where webhook events are sent." }, "eventTypes": { "type": "array", "description": "List of event types the webhook is subscribed to.", "items": { "type": "string" } } }, "additionalProperties": false }
webhook-scope
Scope of the webhook. Possible values: 'Account', 'iTwin'.
{ "type": "string", "description": "Scope of the webhook. Possible values: 'Account', 'iTwin'.", "enum": [ "Account", "iTwin" ] }
Error
Contains error information.
One of a server-defined set of error codes.
A human-readable representation of the error.
The target of the error.
{ "type": "object", "description": "Contains error information.", "properties": { "code": { "type": "string", "description": "One of a server-defined set of error codes." }, "message": { "type": "string", "description": "A human-readable representation of the error." }, "target": { "type": "string", "description": "The target of the error.", "nullable": true } }, "required": [ "code", "message" ], "additionalProperties": true }
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.
{ "type": "object", "title": "Error Response", "description": "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.", "properties": { "error": { "description": "Error information.", "$ref": "#/components/schemas/Error" } }, "required": [ "error" ], "additionalProperties": false }
Was this page helpful?