Help Center/Webhooks & Events

Setting up webhook endpoints

6 min read Updated February 14, 2026

Overview

Webhooks let ComplianceGrid push events to your application in real-time instead of requiring you to poll for updates. Common use cases include screening result notifications, filing status changes, and data freshness alerts.

Registering a Webhook Endpoint

In the Developer Portal (Dashboard → Developer → Webhooks), click Add Endpoint and provide:

  • URL — The HTTPS endpoint on your server that will receive events
  • Events — Which event types to subscribe to
  • Secret — Auto-generated signing secret for verifying webhook payloads

Endpoint Requirements

Your webhook endpoint must:

  • Accept POST requests with a JSON body
  • Return a 2xx status code within 30 seconds
  • Be served over HTTPS (no plain HTTP)
  • Be publicly accessible (not behind a firewall or VPN unless you whitelist our IPs)

Example Endpoint (Express.js)

javascript
app.post('/webhooks/compliancegrid', express.json(), (req, res) => {
  const event = req.body;

  switch (event.type) {
    case 'screening.completed':
      handleScreeningResult(event.data);
      break;
    case 'filing.status_changed':
      handleFilingUpdate(event.data);
      break;
    default:
      console.log('Unhandled event type:', event.type);
  }

  res.status(200).json({ received: true });
});

Testing Webhooks

Use the Send Test Event button in the Developer Portal to send a sample event to your endpoint. In sandbox mode, all events are simulated — no real data is sent.

IP Allowlisting

If your endpoint is behind a firewall, whitelist our webhook source IPs. The current IP list is available at https://api.compliancegrid.ai/.well-known/webhook-ips.

Was this article helpful?