Introduction

Webhook extension

The Oneflow Webhooks extension lets you subscribe to notifications for most events that can happen to contracts in your account. This way, you can seamlessly integrate Oneflow into your system's existing workflows and make sure to stay up to date with the latest changes in Oneflow.

Setting up your webhook

To set up a webhook in Oneflow, you must enable the Webhook extension in the Oneflow application. Then you can add a new webhook with a URL to which Oneflow will send the notifications. Please, see the Working with webhooks section to learn how to create a new webhook.

Security

For security reasons, to validate the authenticity of the webhook request, we recommend using a signature. For that purpose, we add the signature attribute to each notification we send to your integration.

The signature is calculated by building the SHA1 hash of the callback ID attribute concatenation in the notification and your Sign key (see Working with webhooks). You can enter a Sign key in the Oneflow web application during the webhook setup. Below is an example of how the signature is generated:

sha1(callback_id + sign_key)

You can calculate this SHA1 hash in your integration and compare it to the webhook signature attribute for each notification you receive. If they match, you can be sure that the notification is authentic.

How to respond

Please respond with an HTTP status code of 200 when the webhook notification has been received and successfully handled. We will ignore the response body, so you can leave that empty.

Error handling

Any response other than 200 is considered an error and causes the webhook notification to be resent.

The system will retry sending a webhook notification, increasing the time between each retry: 1, 5, 10, 30, 60, 300, 600, 1800, and finally 3600 seconds.

📘

Note:

Attempts to send a webhook notification can cause Oneflow to send webhooks multiple times, and your system needs to be able to handle receiving them. You can check if you received the notification before using the callback ID.

Request format

The notification we send is a regular HTTP POST request with the content-type header application/json; charset=UTF-8

The request body is a JSON object with the events that triggered the notification:

{
	"contract": {
		"id": 101
	},
	"callback_id": "eaf850991bb7c273a56dcdeb265d30006fdc9de0",
	"events": [{
		"created_time": "2020-07-06T15:14:14+0000",
		"id": 2322,
		"type": "contract:publish"
	}],
	"signature": "7a581695d9ff8c41de4d85554b6852f7cf6f97b0"
}

Please see the Webhook and event section for the exact data model.