Webhooks (beta)

How webhooks work

1. You register a webhook in the Cognism platform Settings → Webhooks.
   A registration is simply a delivery URL plus the list of event types you want to receive.
2. Cognism watches for events on the records you track. Person events cover people you have already revealed with credits. Company events cover companies you have explicitly added to your tracked list.
3. When an event happens, Cognism sends an HTTPS POST to your delivery URL with a small, signed JSON payload that identifies the person or company and the event.
4. Your endpoint responds with a 2xx status within 5 seconds. If it doesn't, Cognism retries with exponential backoff.
5. You enrich the record by looking the UUID up in the Connect API or the Cognism platform. The webhook tells you what changed and to whom; it does not carry the details of the change.

Two kinds of webhook

Contact webhooks

Revealing a contact in Cognism spends a credit. Every person you have paid to reveal is
automatically a tracked person for your account for 12 months from that reveal. A contact webhook delivers events for all of those people. You do not maintain a list yourself, and you cannot add a person without revealing them.

Company webhooks

Companies are not revealed with credits, instead, your account has one tracked companies list that you fill yourself with the companies of interest. Company webhooks deliver events only for companies on that list. A company webhook with an empty list delivers nothing.

The list is shared by every company webhook on your account and holds up to 1,000 companies. Adding companies does not consume credits. Removing a company stops future deliveries only.

Contact events

Company events

A webhook can only subscribe to events of its own type. Mixing person and company event types on one registration is rejected.

Configuring webhooks in the platform

Go to Settings → Webhooks. The Registrations table lists every webhook on your account with its delivery URL, type, event types, status and creation date.

Register a webhook

1. Click Register webhook.
2. Enter the Delivery URL. It must be HTTPS and must respond within 5 seconds.
3. Choose the type: Contact events or Company signals.
4. Tick the event types you want. Greyed-out options are already used by another webhook on your account.
5. Save. Copy the signing secret shown after creation and store it securely. You will need it to verify deliveries. You can reveal it again later from the webhook menu.

Edit, disable or delete

Use the ⋮ menu on a row to:

• Edit the delivery URL or event types.
• Disable the webhook. Nothing is delivered while it is disabled, but it keeps its event types.
• Delete the webhook. Its event types become available for other webhooks.

Track companies (company webhooks only)

Add the companies you want to follow to your tracked companies list. Until the list contains at
least one company, a company webhook will not deliver anything.

Tracked companies

Example: add companies to the tracked list

POST /tracked-companies
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "companyUuids": [
    "8004c0af-4226-3a36-a1a4-b88d32eaf730",
    "1b4e28ba-2fa1-11d2-883f-0016d3cca427"
  ]
}

Company UUIDs are the same identifiers returned by the Connect API companies search. A request that would push the list past 1,000 companies is rejected in full with 409.

Error responses

Test payloads

The test action sends a real delivery for one of the webhook's subscribed event types, with all
UUIDs set to 00000000-0000-0000-0000-000000000000 and eventSeq set to
ffffffffffffffff0000000000000001. Treat any payload with those values as a test.

Securing your endpoint

Deliveries are signed so you can confirm they came from Cognism and were not altered in transit.

Every request carries three headers:

To verify, compute HMAC-SHA256 over "{svix-id}.{svix-timestamp}.{raw body}" with your signing secret (strip the whsec_ prefix and base64-decode the rest), then compare it to the signature in the header using a constant-time comparison. Reject requests whose timestamp is more than five
minutes old to prevent replays.

Cognism uses the Svix signature scheme, so the official Svix libraries for Node, Python, Go, Java, .NET, Ruby, PHP and Rust verify payloads in a few lines:

import { Webhook } from 'svix';

const wh = new Webhook(process.env.COGNISM_WEBHOOK_SECRET);
const payload = wh.verify(rawBody, {
  'svix-id': req.headers['svix-id'],
  'svix-timestamp': req.headers['svix-timestamp'],
  'svix-signature': req.headers['svix-signature'],
});

Always verify against the raw request body, not a re-serialised object. Keep the secret out of
source control and rotate it if it leaks.

Delivery, retries and timing

Respond fast, process later

Return a 2xx as soon as you have stored or queued the payload. Any 2xx counts as success. A non-2xx response, a connection error or a response slower than 5 seconds counts as a failure.

Retries

Failed deliveries are retried with exponential backoff, several times over roughly one day. Retries carry the same svix-id and the same body. If every retry fails, the message is marked failed and you can inspect it through the delivery-history endpoints.

Handle duplicates

Delivery is at-least-once. The same event can occasionally arrive more than once, for example if your endpoint timed out after it had already processed the request. Deduplicate on eventType plus data.eventSeq, or on the svix-id header.