System ServicesWebhooksBeta

Create subscription

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.