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:

"webHook": {
  "enabled": true,
  "endpoint": "http://www.example.org/automation"
}

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

{
  "orderId":"07c6ad8c-d1ba-4e73-9bbf-c70a085a449c",
  "eventType":"OrderAccepted"
}

Common configuration

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

"webHook": {
  "enabled": true,
  "key": "QueryParameterKey",
  "endpoint": "http://www.example.org/automation"
}

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.

"webHook": {
  "enabled": true,
  "connectionTimeout": "PT60S",
  "endpoint": "http://www.example.org/automation"
}

Adding simple security

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

"webHook": {
  "enabled": true,
  "secret": "HeaderSecret",
  "endpoint": "http://www.example.org/automation"
}

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.

"webHook": {
  "enabled": true,
  "endpoint": "https://www.example.org/automation"
}

Adding keys:

"webHook": {
  "enabled": true,
  "useSslTrustAll": false,
  "useSslClientCert": false,
  "sslKeyFile": "keyfile",
  "sslKeyPassword": "password",
  "endpoint": "https://www.example.org/automation"
}

Adding client authentication:

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

Order event subscriptions

The events that are sent as webhooks are the following:

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

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