Build sanctions monitoring into your backend

1. Configure your organization integration

1. Sign in and open API integrations. Regular organization members and administrators can manage their organization’s integration.
2. Create an integration key and securely save the raw key shown once. Never expose it in browser JavaScript or query strings.
3. Create an HTTPS webhook destination and save its signing secret in your receiving backend. Set a default destination, or supply its channel ID when creating a subscription.

Integration keys authorize the versioned subscription endpoints, not dashboard administration or credential management. User sessions and organization ownership protect the management screens.

2. Create a subscription from your server

Send this request to your deployed API base URL. Only the name is required in the JSON body; both authentication and idempotency headers are required.

POST /api/v1/subscriptions
X-Api-Key: <your-integration-key>
Idempotency-Key: customer-456-screening-v1
Content-Type: application/json

{
  "name": "John Doe",
  "externalReference": "customer-456"
}

A successful request returns HTTP 201. This is an abbreviated response; use the OpenAPI specification for the full model.

{
  "subscriptionId": "<subscription-id>",
  "screeningStatus": "pending",
  "matches": [],
  "screenedAt": null
}

Initial screening runs asynchronously. Do not interpret empty matches on a pending response as a completed check.

• GET /api/v1/subscriptions/{id} returns the current status, candidates, screening timestamp, and errors.
• DELETE /api/v1/subscriptions/{id} cancels monitoring and returns HTTP 204.

Retry safely with idempotency

Keep the same Idempotency-Key for retries of the same creation request with the same integration key. A changed payload with that key returns HTTP 409. Use a new key for a different subscription. externalReference is your correlation value, not a uniqueness constraint or retry mechanism.

Choose a notification destination

Supply webhookChannelId to select a destination, or omit it to use your organization default. Without either, the subscription is still created but webhook delivery is not configured. The destination is captured at creation; changing the default does not update existing subscriptions.

3. Verify the webhook signature before processing

X-Webhook-Secret contains the lowercase hexadecimal HMAC-SHA256 of the exact UTF-8 request body. It does not contain the signing secret itself. Compute the expected HMAC using the complete secret, including the whsec_ prefix, and compare it in constant time.

import { createHmac, timingSafeEqual } from 'node:crypto';

// rawBody must contain the exact request bytes, before JSON parsing.
// signingSecret is the complete whsec_... value from API integrations.
function validSignature(rawBody, header, signingSecret) {
  if (!Buffer.isBuffer(rawBody) || !/^[a-f0-9]{64}$/.test(header)) {
    return false;
  }

  const expected = createHmac('sha256', signingSecret).update(rawBody).digest();
  return timingSafeEqual(expected, Buffer.from(header, 'hex'));
}

Read the raw body before JSON middleware changes it. Reject missing or invalid signatures before processing. After verification, atomically deduplicate the body’s eventId in persistent storage and durably accept or queue the event before returning 2xx. Deliveries are at least once; a valid signature alone does not prevent replay.

This helper verifies a signature; your receiver must also enforce body-size limits, validate the event, persist deduplication, and implement its processing logic. Rotate secrets through the destination details and coordinate the receiving configuration with that change.

4. Monitor outcomes and recover from failures

The webhook receives initial screening results and later changes. Inspect HTTP attempts in API integrations → destination details → Event deliveries. Screening and delivery statuses are separate. Exhausted delivery failures can be retried when eligible, preserving event identity.

• 400 / 401: correct the request or credentials before retrying.
• 404: verify the subscription ID and organization ownership.
• 409: resolve the idempotency conflict; do not blindly repeat a different payload.
• 413: reduce the request size. Creation bodies are limited to 64 KiB.
• 429: honor Retry-After. The current subscription API quota is 120 requests per minute per organization per API process, shared across its keys.

For transport failures, retry creation using the original idempotency key. A screening status of failed requires investigation even when previous candidates remain visible.