Skip to main content

Creating webhooks #NextGen

  • Updated

Note

The Webhooks feature is available to everyone from version 23.2.3 onwards.

As the feature is currently in the beta phase, we are monitoring it closely and are making sure that all our events are properly triggered. Have you experienced any issues? Please reach out to us at: api[at]xentral.com.

A webhook allows you to receive information about events happening in Xentral in an external system. For example, you could get a notification in your application every time a new sales order is created. The information is sent to your external system via an HTTP POST request.

Tip

To learn more technical information about webhooks and possible events, check out the developer documentation.

Create webhooks

Note

Creating webhooks requires administrator privileges.

To create a webhook:

  1. Go to createbookmark_x21.png Settings > Integrations > Webhooks. You will see a list of all webhooks in active use.

  2. Click on + Create new Webhook. If there are no webhooks active, you will find the button in the middle of the screen. Otherwise you will find it on the top right of your list.

  3. Enter a unique Name for your webhook. The name should not exceed 100 characters.

  4. Enter the URL endpoint that should receive information from the webhook. Only secure https URLs are allowed. The URL should not exceed 255 characters.

  5. Take note of the Signature key. It will be copied to your clipboard, when you finish creating the webhook. This field is automatically filled with a random 20 character string which serves as the signature key. If you prefer, you can overwrite it with your own string that consists of 20 to 255 characters or you can copy it to clipboard yourself by clicking x21_preview_icon.png in the Signature Key field and copying the string.

    Important

    The signature key enables the receiving system to ensure that the information really is from Xentral . Don't show this key publicly or hardcode it into your system.

    You can find out how you can use the signature key to check the signature in the linked section: Check signature of your webhook.

  6. Select an Event. It is also possible to select multiple events, if needed. The webhook sends out information to the endpoint every time one of these events happen.

  7. Click Create. The signature key will be copied to clipboard and appear on screen one last time. Click CopyIcon.png if you want to make sure the key has been copied.

  8. Close the window.

Your new webhook is displayed in the list of active webhooks. In the overview you can quickly see the URL endpoints and the attached events for every webhook you created.

Edit and delete webhooks

All webhooks will be listed under createbookmark_x21.png Settings > Integrations > Webhooks. When you click PenIcon.png Edit you have two options:

  • Edit settings - You can change the name, URL endpoint and signature key as well as add or remove events from the webhook. If you change the signature key you must also update it in your external application.

  • Delete webhook - Click on Delete webhook below the list of events and confirm the deletion request. The external system won't receive new information about events in Xentral anymore.

Check signature of your webhook

The header of the HTTP request of the webhook consists of the xentral-signature and the xentral-request-timestamp.

You can calculate the xentral-signature as follows:

  1. Create the message out of the RequestBody and the xentral-request-timestamp. For this you need to write down the RequestBody and then append the xentral-request-timestamp without adding any spaces or similar.

  2. Create a HMAC of the message with a SHA-256 hash function and use the signature key you defined when creating the webhook as the Secret Key.

  3. Compare the hexadecimal output of the HMAC with the xentral-signature in the header of the HTTP request. They should be identical.

We can see how this works in the following example where we use the following values:

  • RequestBody: {"type":"com.xentral.salesOrder.protocolCreated.v1","body":{"createdAt":"2024-05-28T17:30:07+02:00","salesOrderId":169,"salesOrderProtocolId":586}}

  • xentral-request-timestamp: 1716910210

  • Secret Key: e4nRJ04Ss2m3EkQxn19V

This leads to the following message:

Message: {"type":"com.xentral.salesOrder.protocolCreated.v1","body":{"createdAt":"2024-05-28T17:30:07+02:00","salesOrderId":169,"salesOrderProtocolId":586}}1716910210

The message and the Secret Key lead to the following xentral-signature in hexadecimal code when using a HMAC with SHA-256: 67b9db5fbe8add6c5b073f42091f593e994de32c83741573015442c154214bcf.

Related articles

Visit the Academy - you'll find videos for most topics