Working with Webhooks in Dynamics 365 Business Central

Article
12/03/2018

Webhooks is the way to get notified if an entity changes in Dynamics 365 Business Central. For general information about webhooks, see Push notifications via webhooks in Microsoft REST API Guidelines.

Register a webhook subscription

Using webhooks requires the client/subscriber to perform a handshake with Dynamics 365 Business Central to register the webhook subscription.

POST https://{businesscentralPrefix}/api/beta/subscriptions 
Content-type: application/json
{
  "notificationUrl": "https://{notificationUrl}",
  "resource": "/api/beta/companies(f64eba74-dacd-4854-a584-1834f68cfc3a)/customers",
  "clientState": "optionalValueOf250"
}

Once the POST is issued against the subscription API to create the subscription, Dynamics 365 Business Central will issue a request to the notificationUrl, passing a validationToken parameter on the query string. Subscriber needs to perform the handshake by returning validationToken in the response body and provide status code 200.

If Dynamics 365 Business Central receives the response containing the validationToken, the subscription is registered and webhook notifications will be sent to the notificationUrl.

Important

Handshake is mandatory when creating a subscription and renewing a subscription. In both cases the client has to return the validationToken in the body with response code 200 OK.

Client state

Optionally clientState can be provided in the POST and PATCH 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.

Renewing the subscription

Subscriptions will expire after 3 days, if not renewed before. Subscriptions are renewed by issuing a PATCH request to the subscription.

PATCH https://{businesscentralPrefix}/api/beta/subscriptions({id})

PATCH requests a handshake, just like POST requests, meaning that a subscription cannot be renewed unless the client returns the validationToken in the body.

Subscription expiration time is listed in expirationDateTime property of the subscription.

Notifications and change types

Valid subscriptions push the notifications on every entity update.

Each notification sent to the subscriber (notificationUrl) can contain multiple notifications from different subscriptions. Here is a sample notification payload:

{
  "value": [
    {
      "subscriptionId": "webhookItemsId",
      "clientState": "someClientState",
      "expirationDateTime": "2018-10-29T07:52:31Z",
      "resource": "api/beta/companies(b18aed47-c385-49d2-b954-dbdf8ad71780)/items(26814998-936a-401c-81c1-0e848a64971d)",
      "changeType": "updated",
      "lastModifiedDateTime": "2018-10-26T12:54:20.467Z"
    },
    {
      "subscriptionId": "webhookCustomersId",
      "clientState": "someClientState",
      "expirationDateTime": "2018-10-29T12:50:30Z",
      "resource": "api/beta/companies(b18aed47-c385-49d2-b954-dbdf8ad71780)/customers(130bbd17-dbb9-4790-9b12-2b0e9c9d22c3)",
      "changeType": "created",
      "lastModifiedDateTime": "2018-10-26T12:54:26.057Z"
    },
    {
      "subscriptionId": "webhookCustomersId",
      "clientState": "someClientState",
      "expirationDateTime": "2018-10-29T12:50:30Z",
      "resource": "api/beta/companies(b18aed47-c385-49d2-b954-dbdf8ad71780)/customers(4b4f31f0-dc1c-4033-b2aa-ab03ca1d6ebc)",
      "changeType": "deleted",
      "lastModifiedDateTime": "2018-10-26T12:54:30.503Z"
    },    {
      "subscriptionId": "salesInvoice",
      "clientState": "someClientState",
      "expirationDateTime": "2018-10-20T10:55:01Z",
      "resource": "/api/beta/companies(7dbba574-5f69-4167-a43e-fb975045de15)/salesInvoices?$filter=lastDateTimeModified%20gt%202018-10-15T11:00:00Z",
      "changeType": "collection",
       "lastModifiedDateTime": "2018-10-26T12:54:30.503Z"
    }

  ]
}

Created, updated, and deleted identifies the state change for the entity. By collection Dynamics 365 Business Central sends a notification that many records have been created or changed. A filter is applied to the resource, enabling the subscriber to request all entities satisfying the filter.

Notifications are not sent immediately when the record changes. By delaying notifications, Dynamics 365 Business Central can ensure that only one notification is sent, even though the entity might have changed several times within a few seconds.

Note

If Dynamics 365 Business Central cannot reach the subscriber, several retries will be attempted over the next 36 hours. The subscriber must respond with following error codes: 408 - Request Timeout, 429 - Too Many Requests or any error in 500-599 range (5xx). If subscriber responds with any other code than listed, no retries will be attempted and the subscription will be deleted.

Unsubscribing

To remove a subscription, execute a delete request.

Supported entities

The following entities have webhooks support:

accounts
companyInformation
countriesRegions
currencies
customerPaymentJournals
customers
dimensions
employees
generalLedgerEntries
itemCategories
items
journals
paymentMethods
paymentTerms
purchaseInvoices
salesCreditMemos
salesInvoices
salesOrders
salesQuotes
shipmentMethods
unitsOfMeasure
vendors

Notes for on-premise

By default, a subscription lives for 3 days if it is not renewed. The value is specified in the CustomSettings.config file under the ApiSubscriptionExpiration entry. There is a maximum number of subscriptions specified in the ApiSubscriptionMaxNumberOfSubscriptions in the CustomSettings.config file.