Help Center/Webhooks & Events

Setting up webhook endpoints

4 min read Updated October 22, 2026

Where webhooks exist

Webhooks are available for two features: monitoring watchlists (party.status_changed) and risk batch jobs (risk.batch.complete). There is no separate webhook endpoint registry in the Developer Portal; you give the URL when you create the watchlist or batch job.

Registering

Watchlist: POST /v1/monitoring/watchlists with "webhook": { "url": "https://...", "secret": "optional" }. If you omit the secret one is generated (whsec_...) and returned once
Risk batch: POST /v1/risk/batch with "deliveryMethod": "WEBHOOK", webhookUrl and webhookSecret

Endpoint requirements

Accept POST with a JSON body and answer within 10 seconds
HTTPS only, with no credentials in the URL
Publicly resolvable: URLs on localhost, .local or .internal hosts, or that resolve to private or reserved addresses, are refused
Redirects are not followed

Example receiver

javascript

app.post('/webhooks/compliancegrid', express.raw({ type: 'application/json' }), (req, res) => {
  // verify the signature first (see the signature article), then:
  const event = JSON.parse(req.body);
  switch (event.type) {
    case 'party.status_changed': handleStatusChange(event.data); break;
    case 'webhook.test': break;
    default: console.log('Unhandled event type:', event.type);
  }
  res.status(200).json({ received: true });
});

Testing

POST /v1/monitoring/watchlists/{id}/test sends a signed webhook.test event to the watchlist's URL.

Source addresses

We do not publish a fixed list of source IP addresses. Verify the signature instead of relying on the source address.

Was this article helpful?