Configure a webhook

Overview

The Automation API makes it possible to poll for orders to get to a certain state, by instead using a webhook the need to poll goes away. When an order changes state the webhook is activated and the full order content can be retrieved by a single call to the automation API. The webhook is configured under the section "webHook" in the configuration file. The webhook functionality is disabled by default.

Getting started

The simplest webhook configuration without any security looks like this:

<p>"webHook": {
  "enabled": true,
  "endpoint": "http://www.example.org/automation"
}</p>
Click to copy

The endpoint should be configured to accept a POST and can then retrieve the JSON body containing the order id and order state.

<p>{
  "orderId":"07c6ad8c-d1ba-4e73-9bbf-c70a085a449c",
  "eventType":"OrderAccepted"
}</p>
Click to copy

Common configuration

An optional key can be added to the URL as a query parameter to separate different installations e.g.

<p>"webHook": {
  "enabled": true,
  "key": "QueryParameterKey",
  "endpoint": "http://www.example.org/automation"
}</p>
Click to copy

The final URL will be "http://www.example.org/automation/?key=QueryParameterKey

The http connection timeout (optional) can be changed from the default 30 seconds. Parameter is in ISO-8601.

<p>"webHook": {
  "enabled": true,
  "connectionTimeout": "PT60S",
  "endpoint": "http://www.example.org/automation"
}</p>
Click to copy

Adding simple security

Use a secret to sign the body. This will add a SHA256 signature to the http header.

<p>"webHook": {
  "enabled": true,
  "secret": "HeaderSecret",
  "endpoint": "http://www.example.org/automation"
}</p>
Click to copy

The http headers will include "X-Signature" with the signature.

Adding SSL/TLS security

The default is to trust all SSL/TLS connections. Use this to get started and for test.

<p>"webHook": {
  "enabled": true,
  "endpoint": "https://www.example.org/automation"
}</p>
Click to copy

Adding keys:

<p>"webHook": {
  "enabled": true,
  "useSslTrustAll": false,
  "useSslClientCert": false,
  "sslKeyFile": "<keyfile>",
  "sslKeyPassword": "<password>",
  "endpoint": "https://www.example.org/automation"
}</password></keyfile></p>
Click to copy

Adding client authentication:

<p>"webHook": {
  "enabled": true,
  "useSslTrustAll": false,
  "useSslClientCert": true,
  "sslTrustFile": "<trustfile>",
  "sslKeyFile": "<keyfile>",
  "sslKeyPassword": "<password>",
  "endpoint": "https://www.example.org/automation"
}</password></keyfile></trustfile></p>
Click to copy

Order event subscriptions

The events that are sent as webhooks are the following:

  • OrderCreated
  • OrderAccepted
  • OrderSigned
  • OrderRejected
  • OrderCanceled
  • OrderExpired
  • OrderDueDateUpdated

Please see the Automation API how to act on different order states.