System ServicesWebhooks

Create subscription

Beta
Creates a new webhook subscription for a specific external business event, configuring the notification endpoint and event details.

Path parameters

tenantstringRequired

Your Entra Tenant ID. More details.

environmentstringRequired

Your Business Central Environment. More details.

companystringRequired

Your Business Central Company. More details.

Headers

AuthorizationstringRequired

Bearer authentication of the form Bearer <token>, where token is your auth token.

x-api-versiondateOptional

Used for API versioning. More details.

Request

This endpoint expects an object.
notificationUrlstringRequired
The full URL endpoint that will receive webhook notifications when the specified event occurs.
eventNamestringRequired
Represents the specific name of the external business event that triggers the webhook notification.
appIdUUIDOptional

Unique identifier (UUID) of the application associated with the webhook subscription. Use only for webhooks included in custom applications (custom webhooks).

eventVersionstringOptional
Specifies the version of the webhook event. If no version is provided, it defaults to the standard version '1.0'.
clientStatestringOptional

The clientState property must be provided in the POST requests bodies. clientState is included in the body of a webhook notification and can be used as an opaque token; a shared secret, enabling the subscriber to verify notifications. The value can be any string up to 50 characters, we recommend using a unique value for each subscription (ideally as a UUID or a base64 encoded string etc.).

Response

This endpoint returns an object.
@odata.etagstring

An internal property (a version control mechanism used by OData to manage concurrency and track changes in resource entities).

idUUID

Unique identifier (UUID) for a webhook subscription. Required for retrieving or deleting an existing webhook subscription through the API.

companyIdUUID
timestamplong
appIdUUID

Unique identifier (UUID) of the application associated with the webhook subscription. Use only for webhooks included in custom applications (custom webhooks).

eventNamestring
Represents the specific name of the external business event that triggers the webhook notification.
companyNamestring
Name of the company within the Business Central environment for which the webhook subscription is configured.
userIdUUID

Unique identifier (UUID) representing the user who created or modified the webhook subscription.

notificationUrlstring
The full URL endpoint that will receive webhook notifications when the specified event occurs.
lastModifiedDateTimedatetime
clientStatestring

The clientState property must be provided in the POST requests bodies. clientState is included in the body of a webhook notification and can be used as an opaque token; a shared secret, enabling the subscriber to verify notifications. The value can be any string up to 50 characters, we recommend using a unique value for each subscription (ideally as a UUID or a base64 encoded string etc.).

subscriptionTypeenum
Defines the type of subscription supported by the webhook system. Currently, only the "Webhook" type is valid.
Allowed values:
eventVersionstring
Specifies the version of the webhook event. If no version is provided, it defaults to the standard version '1.0'.
subscriptionStatestring
systemCreatedAtdatetime
systemCreatedByUUID

Unique identifier (UUID) representing the user who created or modified the webhook subscription.

systemModifiedAtdatetime
systemModifiedByUUID

Unique identifier (UUID) representing the user who created or modified the webhook subscription.