Configuring webhooks

The API makes use of webhook notificatiosn in order to keep your system informed of changes related to your organisation automatically. An event resource is sent to your webhook receiver whenever a significant event occurs.

The ricloud-py CLI contains a sample implementations of a webhook endpoint.

Creating a webhook config

The only thing needed to create a webhook configuration is the URL to which the API will send outgoing events.

ricloud-py implements a helper command:

> ricloud webhook-config create --url "<webhook receiver URL>"

The equivalent cURL call would look like like:

curl https://ricloud-api.reincubate.com/configs/webhook \
  -X POST \
  -H 'Authorization: Token <your key_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "<webhook receiver URL>"
}'

The response to this request will contain the webhook secret, which will be important to securing your webhook receiver implementation in production.

Verifying event signatures

Each webhook request includes a Ricloud-Signature header which should be used to verify the contents of the request have not been altered. The header also contains a timestamp, which is used in the verification process, in order to counter replay attacks.

ricloud-py includes an implementation of this signature verification process.