Webhooks

A webhook is technically an HTTP POST request. Under the hood, this simple form of messaging can be responsible for a variety of use cases.

In practice, webhooks are used as custom callbacks. These callbacks are triggered when a specific event occurs.

Use cases

The introduction of webhooks reveals a wide variety of use cases:

• Real-time custom data synchronization with external systems.
• Ability to implement more complex real-time business logic from external applications.
• Integration with external BPM platform orchestrators.
• Real-time sending to message brokers such as Azure Service Bus and RabbitMQ.
• External logging or chat services like Slack and Graylog.
• Issue and project tracking systems - create issues in Jira or cards in a Trello list.

Setting things up

The process of triggering a webhook can be divided into two stages.

1. Create a webhook template that specifies the contents of the webhook, as well as the endpoint it will trigger.
2. Then, create an event that will trigger the webhook via its template. Such an event can be raised by the user-defined business rules.

1. Webhook template

The webhook template is just an entity part of the Systems.Config namespace Systems.Config.WebHooks.

The attributes are self-explanatory and must be filled in to meet the requirements of the external system (which will de facto receive the webhook).

Let's see some of the more interesting attribute values in the example below:

• The Repository Name field must have a value that matches the one in the user business rule.

• The URL and Body attributes contain the destination address and the body content of the webhook.
  As you can see, they are provided in interpolated string form.

https://my.extsvc.com:12345/{EntityName}/{Id}

{{
    "Id": "{Id}",
    "Number": "{DocumentNo}",
    "Date": "{DocumentDate}",
    "Subject": "{Subject}",
    "State": "{State}"
}}

Post-evaluation, they should look like this:

https://my.extsvc.com:12345/Srv_Service_Activities/{925bc44b-787e-4e73-b8da-a4dfd2e442b6}

{
    "Id": "925bc44b-787e-4e73-b8da-a4dfd2e442b6",
    "Number": "000015",
    "Date": "13.01.2022",
    "Subject": "Test service activity",
    "State": "New"
}

• The Headers content is straightforward. It contains an authorization token as a constant and a format specifier for the body (application/json).

2. Event (user business rule)

We already have a webhook template, but the final step is to reference it from a user business rule when a particular event occurs.

Let's take a look at the picture below:

This is the definition of a user business rule. The following key points need to be mentioned:

• The business rule is defined for the Applications.Service.ServiceActivities repository.
• It has a defined event of type AGGREGATECLIENTCOMMIT.
• It introduces an action of type WEBHOOK with a single parameter equal to "wh_01".

In other words:

A webhook template with code wh_01 will be triggered on each COMMIT in the ServiceActivities aggregate tree.

Example

We have a user business rule executing a webhook when a service activity is created or updated:

Repository
Applications.Service.ServiceActivities
Events
Event type	Event parameter	Execution priority
AGGREGATECLIENTCOMMIT		Normal
Actions
Action No	Action type	Parameter1 type	Parameter1 value
1	WEBHOOK	Constant	wh_01

The value of the WEBHOOK's Parameter1 is simply the code of the corresponding WebHook entity.

Name	Value
Code	wh_01
Name	Webhook 01
Repository name	Applications.Service.ServiceActivities
URL	http://my-external-system:12345/{EntityName}
Body	{{ "Id": "{Id}", "Number": "{DocumentNo}", "Date": "{DocumentDate}", "Subject": "{Subject}", "State": "{State}" }}
Headers	User-Agent: ERP.net X-Auth-Token: my_security_token
Retry logic	Retry up to 3 times
Notes	Sends an HTTP POST request to the target URL, identifying the updated service activity.

The table above shows the webhook template "behind" the code "wh_01".

Note that the values for the URL and body properties are using string interpolation.

Because a webhook is by definition just an HTTP POST request, this is what the HTTP message would look like:

POST /Srv_Service_Activities HTTP/1.1
Host: my-external-system:12345
User-Agent: ERP.net
X-Auth-Token: my_security_token
Content-Length: 153

{
    "Id": "9b68c23b-e3bc-4aa3-a906-cfa83fe1cdfc",
    "Number": "00001",
    "Date": "12.01.2022",
    "Subject": "Test activity",
    "State": "New"
}

---

See more

• Webhook wiki
• New WebHooks entity
• Webhook action type
• Send a message to Azure Service Bus
• Create a card in Trello
• Send a message in a channel in Slack
• String interpolation

Note

The screenshots taken for this article are from v24 of the platform.