What are webhooks?
A webhook is a non-standard HTTP request that is triggered when something happens in the originating system.
In the case of ITscope, this occurs when new deal or order response documents become available. For example, if a distributor A provides a new delivery note for an order from customer B, a webhook with this information will be sent to the corresponding URL (if everything has been configured correctly).
Structure
ITscope’s webhooks are structured according to the following scheme:
| eventId | ID of the sent webhook |
| timestamp | Timestamp of when the webhook was sent |
| eventType | Type of document that triggered the webhook. Possible values are ORDER, ORDERRESPONSE, DELIVERY and INVOICE |
| transactionStatus | New status of the order or deal (e.g. ARRIVED or PROCESSING) |
| orderId | ID of the order or deal |
| itscopeOrderId | ID of the order or deal assigned by ITscope |
| documentId | ID of the document that triggered the webhook |
| documentUrl | URL to access the actual document via ITscope API |
| transactionId | ID of the transaction |
A webhook for a new dispatch notification could, for example, look like this:
{
"eventId": "e2a6a466-3b62-4bb7-af53-b59aec592b49",
"timestamp": "2023-10-17T11:01:36",
"eventType": "DELIVERY",
"transactionStatus": "ADVISED",
"orderId": "123-SAMPLE-456",
"itscopeOrderId": "SAMPLE-123456-789",
"documentId": "123456789",
"documentUrl": "https://api.itscope.com/2.1/business/documents/123456789-1234-5678-9123-12SAMPLE4567/DISPATCHNOTIFICATION.xml",
"transactionId": "123456789-1234-5678-9123-12SAMPLE4567"
}Set up
The webhook settings can be accessed in the header bar above the profile picture on the right > My Account > Webhooks tab. This page is visible to all users. Changes can only be made if the executing user is a company admin and if the necessary modules have been purchased in the company’s contract
The settings are roughly divided into two areas:
- The access data for the target system can be entered in “Basic Authentication” so that the webhooks can be sent with them if the server of the entered URLs expects such authentication. If a password has already been stored, asterisks are displayed to indicate the length of the password.
- The links to which the respective webhooks should be sent can be entered under URLs. To do this, the respective checkbox must be selected and an https URL must be entered. Only when both are fulfilled will the webhooks be sent. A dummy webhook can be sent to the entered URL using the “Test” button.
The webhook settings are only saved once the “Apply changes” button has been clicked.