Webhook configs

Updated

The webhook config resource is used by the API to send events to your webhook receiver.

An organisation can have a default webook config which is used by all keys within that organisation that don't specify a webhook config of their own.

Attributes

name type description
id webhook config ID Resource identifier.
resource string, always webhook_config Resource type specifier.
organisation organisation ID The organisation the resource belongs to.
url string The url to target when sending events.
secret string The shared secret used to verify event signatures.
state string One of: new, valid, invalid, deactivated.
date_created datetime When the resource was created.

Secret

When a webhook config is created, a secret will be generated alongside it that will be used to sign events sent by the API. It is highly recommended that you implement your webhook receiver to verify the signature of incoming events using this secret. For more details on the signature verification procedure see the webhook configuration docs.

States

  • new has just been created or recently updated but not yet tested.
  • valid has passed validation and is ready to be used. An organisation must have at least one webhook config in this state in order to be useable.
  • invalid has failed the validation test. Must be updated or retested.
  • deactivated has been turned off by the owning organisation.

Create POST /configs/webhook

This action will create a webhook_config.test task in order to validate the endpoint details. If the webhook receiver is not yet setup, this test will likely fail and set the config to the invalid state. However, the config can always be re-tested using the test action.

Parameters

name type description
url required The URL of your webhook receiver.

Using cURL

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

Using ricloud-py

import ricloud

webhook_config = ricloud.WebhookConfig.create(url='https://www.mywebhook.com/webhooks/')

Retrieve GET /configs/webhook/{webhook_config ID}

Using cURL

curl https://ricloud-api.reincubate.com/configs/webhook/<webhook_config ID> \
  -H 'Authorization: Token <your key_token>'

Using ricloud-py

import ricloud

webhook_config = ricloud.WebhookConfig.retrieve(<webhook_config ID>)

List GET /configs/webhook

Webhook configs in the deactivated state are hidden by default and can only be listed by explicit filtering.

Parameters

name type description
state string Filter webhook configs by their state.
date_created datetime filter Filter by resource creation date.

Update POST /configs/webhook/{webhook_config ID}

This action will create a webhook_confg.test task in the background to validate any changes made to the config.

The state attribute can only be changed to deactivated in the case you are essentially retiring a config.

Parameters

name type description
url string Update the URL.
state string Only to new or deactivated.

Using cURL

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

Using ricloud-py

import ricloud

webhook_config = ricloud.WebhookConfig.update_with_id(
  <webhook_config ID>,
  url='https://www.myupdatedwebhook.com/webhooks/'
)

# OR

webhook_config = ricloud.WebhookConfig.retrieve(<webhook_config ID>)

webhook_config.update(url='https://www.myupdatedwebhook.com/webhooks/')

Test GET /configs/webhook/{webhook_config ID}/test

This action creates a webhook_config.test task which sends a test event using the specified configuration. The outcome of the test will update the state attribute of the webook configuration accordingly.

Using cURL

curl https://ricloud-api.reincubate.com/configs/webhook/<webhook_config ID>/test \
  -H 'Authorization: Token <your key_token>'

Using ricloud-py

import ricloud

test_task = ricloud.WebhookConfig.test_with_id(<webhook_config ID>)

# OR

webhook_config = ricloud.WebhookConfig.retrieve(<webhook_config ID>)

test_task = webhook_config.test()

How can we help?

Our support team are here to help!

Our office hours are Monday to Friday, 9 AM to 5 PM GMT. The time is currently 4:59 AM GMT.

We aim to reply to all messages within one working day.

Go to support section › Contact the enterprise team ›
Our awesome support team

Can we improve this article?

We love hearing from users: why not drop us an email, leave a comment, or tweet @reincubate?

© 2008 - 2019 Reincubate Ltd. All rights reserved. Registered in England and Wales #5189175, VAT GB151788978. Reincubate® is a registered trademark. Privacy & terms. We recommend 2FA. Built with in London.