Getting started with webhooks

The Webhook extension lets you subscribe to notifications for most contract events in your account. For example, you can set up a webhook that sends a message when a contract in your account has been signed. This way, you can seamlessly integrate Oneflow into your system's workflows and stay up to date with the latest changes in Oneflow. For the detailed list of events, please see the Webhook type section.

Step 1. Enable the Webhooks extension

To start working with webhooks, you must enable the Webhooks extension in the Oneflow application.

To do that, in the Oneflow application, go to Admin > Account > Extensions page, and toggle the Webhooks bar.

Step 2. Add a new webhook

Now you can add a new webhook with a URL to which Oneflow will send event-related notifications.

To add a new webhook:

1. On the Extensions page, click the Webhooks link.

2. On the Webhooks page, click Create webhook.

3. In the Create webhook window that appears, fill in the URL and, optionally, enter the webhook sign key in the Sign key field.

📘

Note:

The URL must support SSL/TLS (HTTPS).

4. Select the webhook format in the Format field, and then click Confirm.

📘

Note:

There are two format options available:

• Legacy - If you still use the legacy webhook format.
• Current - If you use our new, improved webhooks.

Step 3. Test the webhook endpoint

The easiest way to test webhooks is to use a request bin, a service that will accept any request, respond with a 200 and save parameters, e.g., <https://requestbin.com/>.

To test your integration manually or automatically, you can send webhook requests directly to your service using the command below. Just replace the URL https://www.example.com/my_webhook_endpoint with your service URL and change the contract_id, the event id, and the webhook event type as needed.

curl --request POST \
  --url https://www.example.com/my_webhook_endpoint \
  --header 'content-type: application/json' \
  --data-raw '{
    "contract": {
        "id": 101
    },
    "callback_id": "eaf850991bb7c273a56dcdeb265d30006fdc9de0",
    "events": [{
        "created_time": "2020-07-06T15:14:14+0000",
        "id": 2322,
        "type": "contract:publish"
    }],
    "signature": "7a581695d9ff8c41de4d85554b6852f7cf6f97b0"
}'

import requests
import json

payload = json.dumps({
  "contract": {
    "id": 101
  },
  "callback_id": "eaf850991bb7c273a56dcdeb265d30006fdc9de0",
  "events": [
    {
      "created_time": "2020-07-06T15:14:14+0000",
      "id": 2322,
      "type": "contract:publish"
    }
  ],
  "signature": "7a581695d9ff8c41de4d85554b6852f7cf6f97b0"
})
headers = {
  'content-type': 'application/json'
}

response = requests.post("https://www.example.com/my_webhook_endpoint",
                         headers=headers, data=payload)

print(response.json())

🚧

Note:

Oneflow is not associated with the request bin mentioned above, and you use it at your own risk.