¶ Receiving Webhooks with OData Web Services
In Business Central 14 you may need to receive webhooks with OData Web service instead of an API page. The same process can be used in newer Business Central version, but unlike API page option it requires some additional manual setup.
OData webhooks have the same limitations as Custom API page implementation: you need to make a new page for each kind of webhook and the external service must be able to authenticate to Business Central.
Let's use the same webhook example too:
{
"id": 1,
"no": "01121212",
"name": "Spotsmeyer's Furnishings"
}
¶ Create OData Page
As an optional step you can add your new webhook into the Webhook ID RWU enum. In case you skip this step, you will need to get the webhook endpoint data by description instead. The Implementation part is not needed, since you will enter the endpoint URL manually.
enumextension 4075363 "Test Webhook ID RWU" extends "WebHook ID RWU"
{
value(4075362; "Test OData Page")
{
Caption = 'Test OData Page';
//Implementation = "IWebHook RWU" = "Webhook Test Function RWU";
}
}
Now create a new OData Page in your extension. With our example it can look like this:
page 4075361 "WebHook Odata Test RWU"
{
Caption = 'WebHook Odata Test';
PageType = list;
SourceTable = "API WebHook Entry RWU";
ODataKeyFields = "Entry No.";
layout
{
area(content)
{
repeater(General)
{
field(entryNo; Rec."Entry No.")
{
ApplicationArea = All;
Caption = 'ID';
ToolTip = 'Specifies the value of the ID field';
}
field(id; idNode)
{
ApplicationArea = All;
Caption = 'id';
ToolTip = 'Specifies the customer external id';
}
field(no; noNode)
{
ApplicationArea = All;
Caption = 'no';
ToolTip = 'Specifies the customer number';
}
field(name; nameNode)
{
ApplicationArea = All;
Caption = 'name';
ToolTip = 'Specifies the customer name';
}
}
}
}
trigger OnModifyRecord(): Boolean
var
APIEndpointRWU: Record "API Endpoint RWU";
JsonObj: JsonObject;
PayloadBody: Text;
ResponseBody: Text;
begin
//Recreate the request JSON to save it in webhook entry
JsonObj.Add('id', idNode);
JsonObj.Add('no', noNode);
JsonObj.Add('name', nameNode);
JsonObj.WriteTo(PayloadBody);
//Get the webhook endpoint - unlike API page implmentation, it is not part of the URL
APIEndpointRWU := APIScriptRWU.GET_WEBHOOK_RECORD(ProviderID::RWUTest,WebhookID::"Test OData Page");
//Save new webhook entry attached to the right endpoint
Rec."Endpoint System Id" := APIEndpointRWU."Endpoint System ID";
//For BC 18 and newer versions use instead:
//Rec."Endpoint System Id" := APIEndpointRWU.SystemId;
Rec."Entry System Id" := CreateGuid();
APIScriptRWU.HANDLE_WEBHOOK_CALL(Rec, PayloadBody, ResponseBody, false);
end;
var
APIScriptRWU: Codeunit "API Script RWU";
ProviderID: Enum "Provider ID RWU";
WebhookID: Enum "WebHook ID RWU";
idNode: Integer;
noNode: Text;
nameNode: Text;
}
¶ Webhook Setup
To create a new webhook for your OData page select your API provider from the list and open Webhooks:
Now create a new line with your webhook settings:
- Name your webhook as you see fit in the Description field.
- If you added your page to the enum extension, select the option in Webhook ID field.
- Then insert the OData page ID into Processing API Page ID field. If you did everything correctly, this action will publish the page as a new web service and generate the Endpoint URL.
You can check the web service entry in the list of Web Services:
The web service must be Published to be able to receive webhook calls, and RESTwithUS is using service OData V4 URL as an Endpoint URL. But if needed, you can change the webhook Endpoint URL manually too.
¶ Webhook URL explanation
An example URL of OData web service can look like this: http://restwithus-19:7048/BC/ODataV4/Company('CRONUS International Ltd.')/RWU_TestTest_Webhook_OData
The URL has following parts:
http://restwithus-19:7048/BC/ODataV4– Basic address of your Business Central web service endpoint. Depends on your Business Central installation and service tier name./Company('CRONUS%20International%20Ltd.')– Select the right company in Business Central. This part is not needed if you are querying the default company./RWU_TestTest_Webhook_OData– Call the right web service. Depends on Service Name field in web services list and should be copied from OData V4 URL field.- If you want to call a function in your OData page via API call, you can modify the URL in a following way:
/RWU_TestTest_Webhook_OData/NAV.uNKNOWN_FUNCTIONfor a function calledunknown_functionin the OData page. Please note, that the first letter of the function should be always small.
¶ 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 OData webservice URL. - The request JSON body is not Base64 encoded and you should provide a JSON that matches the nodes defined by your OData page.
- OData page is inserting new Webhook Entry, so the HTTP status is 201 Created.
- Response is not Base64 encoded and is defined by the OData page.
¶ 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.
- 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
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.