WEBHOOK

Name WEBHOOK
Description Used for executing a webhook using business rules.

The webhook to be executed must be an existing webhook template, part of the Web Hooks entity. Parameter 1 specifies its code.

The WEBHOOK action type is executed asynchronously by the server with the limitations, listed in the section below Key points and specific limitations.
Parameter 1 [WEBHOOK CODE] - the code of the webhook to be executed.
Parameter 1 type Constant (string)
Parameter 2 Not used
Parameter 3 Not used
Examples See the Example section below
Version Introduced in: 2022

Compatible events chart

WEBHOOK is compatible with all events.

Event type Compatibility with WEBHOOK
Client commit (e.g. CLIENTCOMMIT, AGGREGATECLIENTCOMMIT) compatible
Document events - (e.g. STATECHANGING, STATECHANGED, VOIDING) compatible
Commit (e.g. COMMIT) compatible
Front-end (e.g. CREATENEW, ATTRIBUTECHANGING, ATTRIBUTECHANGED) compatible

Example:

А business rule executes 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 Web Hook 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 a 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. And because a webhook is by definition just a HTTP POST request, you can see below what the HTTP message would look like, according to the examples above.

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"
}

Key points and specific limitations

  • Each webhook is executed asynchronously by the server, by putting it in a queue (FIFO).
  • Each ERP instance has its own queue, processed independently.
  • There's an intentional pause of 1 second after the execution of each webhook before proceeding to the next one.
  • A queue is capped of 1000 webhooks. Any webhook that would exceed it will be discarded.
  • Only the first webhook discard event will be logged for a calendar day as a warning.
  • Each webhook has a timeout of 10 seconds to get a response from the external system.
  • All HTTP response codes that are not in the range [200-299] (as well as the timeouts) are treated as errors and logged as such.
  • There's a quota allowing logging up to 100 errors per calendar day.

See more