Webhook

If you specified webhook as a notification method, you will receive notifications on the specified url. The webhook will contain the same information as the email. The webhook will be a POST request with the following body:

{
  "messageId": 1,
  "messageRetries": 0,
  "messageContent": [
    {
      "name": "Heineken N.V.",
      "companyId": "nEm9MA1",
      "cocNumber": "34099856",
      "changes": [
        {
          "ruleName": "primary-name-changed",
          "title": "Primary Name",
          "entity": null,
          "changeType": "changed",
          "description": "primaire naam"
          "from": "Heineken N.V.",
          "to": "Jan Heineken N.V."
        }
        // more changes ...
      ]
    },
    // more companies ...
  ]
}

Change object

When a change occurs, you will receive a change object. This change is triggered by a rule. The change object contains the following properties:

Property	Type	Description
ruleName	string	The name of the rule that triggered the change, this will always be for one field or one entity. You can find the rule names in the rules table.
title	string	The title of the change, for changes about fields this will be the name of the field. For changes about entities this will be the entity (for example: director).
entity	string	The entity that changed, this will only be filled if the change is about an entity. For ex. ShareHolder
entityName	string	The name of the entity that changed, this will only be filled if the change is about an entity and if it's relevant. For ex. Johan Gertjes
changeType	string	The type of change, this will be one of the following values: added, removed, changed.
description	string	A dutch description of the change. Is used in the email
from	string	The old value of the field. When the change is about an entity being deleted, this will be the name of the entity.
to	string	The new value of the field. When the change is about an entity being added, this will be the name of the entity.

HMAC signature verification

When you specified a webhook url, a signingKey will be generated for you and returned in the response. This signingKey is used to sign the webhook requests. You can use this signingKey to verify the requests. The signature is in the header of the request. The header is called X-Signature-SHA256 and contains the signature.

The signature is generated by using the HMAC SHA256 algorithm. The signature is generated by using the signingKey as the key and the body of the request as the message. The signature is a hexadecimal string. You can use the following code to verify the signature:

const crypto = require('crypto');
const header = req.headers;
const providedSignature = header['x-signature-sha256'];
const body = req.body;

// Computing the expected signature
const hmac = crypto.createHmac('sha256', secret);
hmac.update(body);
const expectedSignature = hmac.digest('hex');

// Comparing the signatures
if (providedSignature !== expectedSignature) {
  // Signature is invalid
}