Skip to main content
Topograph uses webhooks to notify you about asynchronous events:
  1. Data Retrieval: When company data or documents are ready (verification data).
  2. Monitoring: When a monitored company changes (Monitoring API).

​
Configuration

You configure webhooks in the Topograph Dashboard under Developers > Webhooks. We use Svix for reliable webhook delivery.

​
Verification (Security)

You should verify every webhook to ensure it actually came from us.

​
1. Get your signing secret

You can find your endpoint’s signing secret (starting with whsec_) in the Dashboard.

​
2. Verify the signature

We include headers in every request to allow verification:
  • svix-id: Unique message ID
  • svix-timestamp: Timestamp
  • svix-signature: The signature itself
Use the Svix libraries to verify signatures easily. 
import { Webhook } from 'svix';

const secret = 'whsec_...';
const headers = req.headers;
const payload = req.body;

const wh = new Webhook(secret);
// Throws an error if verification fails
const evt = wh.verify(payload, headers);

​
Event Types

​
Verification data events

When you request data via /v2/company, we send updates as data becomes available. 
{
  "type": "company.data_retrieved",
  "data": {
    "requestId": "req_123...",
    "companyId": "DE123456",
    "dataPoints": {
      "companyProfile": { "status": "succeeded" }
    },
    "company": {
      // ... updated company data ...
    }
  }
}

​
Monitoring Events

When a monitored company changes status or details. 
{
  "type": "monitor.update",
  "data": {
    "monitorId": "mon_123...",
    "companyId": "DE123456",
    "changeCategories": ["status", "address"],
    "monitorHasBeenDeactivated": false
  }
}

​
Retry Policy

If your server returns an error (non-2xx status) or times out, we will retry delivery with exponential backoff.
  • First retry: Immediate
  • Subsequent retries: Increasing delays (seconds, minutes, hours)
  • Duration: We retry for up to 3 days
Ensure your webhook endpoint is idempotent and responds quickly (return 200 OK immediately, process later).