¶ Receiving webhooks with Default API Page
Let's have a simple example of an external service that works with Customers – and when a customer is changed there, the service can call a webhook and send a simple JSON body like this:
{
"id": 1,
"no": "01121212",
"name": "Spotsmeyer's Furnishings"
}
The goal is to receive the webhook in Business Central and process it (for example make some changes in Business Central data).
¶ Translate the Webhook Call with a Third-Party Service
Unfortunately, Business Central API does not allow you to make an endpoint, that will be able to receive any JSON (you need to predefine the JSON structure).
Plus the external service may not be able to authenticate to Business Central, because webhooks are many times called without any authentication and Business Central API requires it (Basic auth for on-prem, OAuth 2 for online).
The solution for both problems is to prepare some kind of a third-party service (e.g. Power Automate or Azure functions), that will:
- Receive the webhook from an external service.
- Authenticate to Business Central API.
- Call the Business Central webhook endpoint and pass the JSON data in predefined, Base64 encoded form.
The Default API Page and Default API Page Function webhooks both require following payload:
{
"payloadBase64Body": "ewogICAgImlkIjogMSwKICAgICJubyI6ICIwMTEyMTIxMiIsCiAgICAibmFtZSI6ICJTcG90c21leWVyJ3MgRnVybmlzaGluZ3MiCn0="
}
The payloadBase64Body node is mandatory and must contain Base64 encoded JSON of the original webhook.
¶ Webhook Setup
To create a new webhook select your API provider from the list and open Webhooks:
Name your webhook as you see fit in the Description field and then choose one of the two predefined options in Webhook ID field (Default API Page Function or Default API Page):
- Description – Internal description of the webhook.
- Webhook ID – Both default options expect the same predefined Base64 encoded JSON body. The only difference is, that
Default API Pageendpoint returns HTTP status 201, andDefault API Page Functionreturns HTTP status 200. - Processing API Page ID – ID of the API page in Business Central, that will receive the webhook call. This field will be generated automatically.
- Endpoint – URL of the webhook, that should be called by your third-party service. This field will be generated automatically.
- Asynchronous Processing – With asynchronous processing the webhook endpoint always returns HTTP status 200 or 201 and a predefined JSON body (
{"Status":"200 OK"}). Received JSON data are not processed immediately, but the job is scheduled in Job Queue and will start in asynchronously a few seconds. For more details see guideline Processing webhooks. - Status is now
Open, meaning you can update the webhook definition.
¶ Call the Webhook
Let's now try to call the webhook endpoint from Postman (the webhook must be Released and you must be able to access Business Central API):
Please note a few details:
- The HTTP verb is always
POSTand you are calling the endpoint URL from webhook list in RESTwithUS. - This is the
Default API Pageoption, therefore the Business Central API returns status 201 Created. - With default page/function options, the response is Base64 encoded too. It is sent in
responseBase64Bodynode.
¶ Webhook Entries
Each webhook call creates a new Webhook Entry. To view the list of those entries select your webhook from the list and open Webhook Entries:
- The Request Payload field contains recieved JSON body (decoded from Base64 in this case).
- If the webhook is
Asynchronous, the Status will beScheduledat first. Processedwebhooks were already processed by RESTwithUS and a required action was taken. (See guideline Processing webhooks.)- If some error appears during webhook processing, the Status will be
Errorand you will see an error message in Error Message field.
¶ Processing the Webhook Call
Of course this is not the end. You just registered a webhook call in Business Central and you need to process the data somehow. For more details see guideline Processing webhooks.