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"
}
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"
}
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"
}
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"
}
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"
}
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"
}
Event subscriptions
The events that are sent as webhooks are the following:
- OrderCreated
- OrderDocumentUpdated
- OrderAccepted
- OrderSigned
- OrderRejected
- OrderCanceled
- OrderExpired
- OrderDueDateUpdated
- OrderSignersUpdated
- OrderDescriptionUpdated