iTwin Webhooks icon

iTwin Webhooks

iTwin Webhooks API for event subscription and management

Actions4

Overview

This node integrates with the iTwin Webhooks API to create and manage webhook subscriptions for event notifications. It allows users to register webhooks that listen to specific event types within either an Account or an iTwin scope. This is useful for automating workflows triggered by changes or activities in the iTwin platform, such as updates to digital twins or project events.

A common scenario would be setting up a webhook to notify your system whenever a new event occurs in a particular iTwin project, enabling real-time processing or alerting. For example, you could create a webhook that triggers when a design model is updated, allowing downstream automation like sending notifications or updating dashboards.

Properties

Name Meaning
Callback URL The URL where webhook event payloads will be sent.
Secret Optional secret string used to secure webhook payloads. If not provided, one will be generated automatically.
Scope Defines the scope of the webhook subscription. Possible values: Account (webhook applies to the entire account) or iTwin.
Scope ID Required if Scope is iTwin. The globally unique identifier of the iTwin scope for the webhook. Not needed if Scope is Account.
Event Types A JSON array listing the event types the webhook should subscribe to.
Options Additional optional settings:
  Custom Payload Allows overriding the default webhook request body with a custom JSON payload. Can enable/disable this feature and specify the JSON content.

Output

The node outputs an array of JSON objects representing the response from the iTwin Webhooks API after creating the webhook. Each item corresponds to the created webhook's details or result data returned by the API.

  • The output field json contains the webhook creation response.
  • No binary data output is indicated.

Dependencies

  • Requires an API authentication token credential for the iTwin platform (OAuth2-based).
  • Uses the iTwin Webhooks OpenAPI interpreter internally to map operations and execute requests.
  • The node expects network access to the iTwin Webhooks API endpoint.
  • No additional environment variables are explicitly required beyond the API credentials.

Troubleshooting

  • Unknown operation error: If the specified operation is not recognized, ensure the "Operation" property is set correctly to "Create webhook".
  • Missing required parameters: When using the iTwin scope, the Scope ID must be provided; otherwise, the API call will fail.
  • Invalid callback URL: Ensure the callback URL is reachable and properly formatted to receive webhook events.
  • Authentication errors: Verify that the API key or OAuth2 credentials are valid and have sufficient permissions.
  • JSON parsing errors: The Event Types and custom payload fields expect valid JSON input; invalid JSON will cause failures.
  • To handle errors gracefully, enable the node’s "Continue On Fail" option to capture error messages in the output instead of stopping execution.

Links and References

Discussion