Webhooks

To get updated information about a task and its state, you can poll the automation API to get the current state.

However, using a webhook is much more efficient. When a task changes state, the webhook is activated and will push information
to the external service that can then fetch the full task from the automation API.

By doing this, we create an event-driven architecture meaning polling the API is no longer needed.

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

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

orderId is deprecated in favour of taskId and will be removed in a future release. Their values are identical.

Configuration

An optional key can be added to the URL as a query parameter to separate different installations, for example:

"webHook": {
  "enabled": true,
  "key": "QueryParameterKey",
  "endpoint": "http://www.example.org/automation"
}
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, which is 30 seconds. The parameter is in the ISO-8601 duration format:

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

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

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

Adding keys:

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

Adding client authentication:

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

Event subscriptions

The events that are sent as webhooks are the following:

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