Skip to content

Working with webhooks

Setup a webhook integration to allow Consumer Intelligence to push events of interest to you as an alternative mode of data transport.

Before you begin

The provided example values in this guide must be changed with the values of your client. Replace <client_id> with your client id, and <client_secret> with your client secret.

Establish a webhook connection

Step 1 - Prepare the Webhook URL

In order to receive Webhook deliveries from Consumer intelligence you need a URL which can receive data from our request servers

The webhook URL should answer with a HTTP status code 200 on all our requests otherwise we will resend the delivery at a later time. We might resend a delivery anyway so Processing a webhook delivery should be idempotent.

Step 2 - Setup

You must have already signed up as an organization with Dun & Bradstreet and have your sandbox credentials from the developer portal. See Getting started guide for help.

Step 3 - Authentication

First, you will need an access_token from the Authentication API (POST:https://login.bisnode.com/sandbox/v1/token.oauth2).

Don't forget to change credentials

Don't forget to replace <client_id> with your client id, and <client_secret> with your client secret.

curl -X POST https://login.bisnode.com/sandbox/v1/token.oauth2 \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials&scope=bci" \
     -u "<client_id>:<client_secret>"

The property access_token from the response should be used for all other API requests in the Authorization header as the Bearer token.

Step 4 - Create a Webhook

Use POST:/v3/webhooks to create a webhook that will listen for events

curl -X POST https://sandbox-api.bisnode.com/consumer-intelligence/v3/webhooks \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <access_token>" \
     -d '{
       "url": <prepared-webhook-url>,
       "events": ["*"],
       "description": "a webhook listening for all event types"
     }'

In the response you will find a secret, save this for the next step. If you lose the secret it cannot be recovered, you will need to remove the webhook and create a new one.

Step 5 - Verifying the Webhook Delivery

When a Webhook has been successfully created, a PING event will be sent to the specified URL.

The webhook delivery has two headers CI-SIGNATURE-TIMESTAMP, and CI-SIGNATURE-SHA256.

To ensure security, you must verify the signature and validate the timestamp before processing the delivery. Start by creating a SHA-256 hash using the timestamp and body of the request, separated by a dot (.), with the secret key obtained when the webhook was created. 

echo -n "<timestamp>.<body>" | openssl dgst -sha256 -hmac "<secret>"

Additionally, check the validity of the CI-SIGNATURE-TIMESTAMP to ensure it is not older than a few minutes, which helps prevent replay attacks and is an essential part of the validation process.