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

​
company.updated

Sent when company data is retrieved or updated. Webhooks are sent progressively as data becomes available - you may receive multiple webhooks for the same request as different data points complete. The payload matches the response from GET /v2/company/{requestId} with an added type field. 
{
  "type": "company.updated",
  "request": {
    "companyId": "932884117",
    "countryCode": "FR",
    "requestId": "86c082a6-c9a0-4243-87d8-7ae18f0ee13a",
    "dataStatus": {
      "dataPoints": {
        "companyProfile": { "status": "succeeded" },
        "availableDocuments": { "status": "in_progress" }
      }
    }
  },
  "company": {
    "id": "932884117",
    "countryCode": "FR",
    "legalName": "TOPOGRAPH",
    "status": {
      "localStatus": "Immatriculée",
      "isActive": true,
      "standardized": "active"
    },
    "legalAddress": {
      "streetAddress": "123 Rue Example",
      "city": "Paris",
      "postalCode": "75001",
      "countryCode": "FR"
    }
  },
  "documents": {
    "tradeRegisterExtract": {
      "id": "trade_register_extract",
      "name": "Extrait Kbis",
      "format": "pdf",
      "url": "https://..."
    }
  }
}
Key fields:
FieldDescription
typeEvent type identifier (company.updated)
request.requestIdUnique identifier to correlate webhooks with your original request
request.dataStatusStatus of each data point (succeeded, failed, in_progress, pending)
companyCore company profile information
ultimateBeneficialOwnersArray of beneficial owners (when available)
legalRepresentativesArray of legal representatives (when available)
shareholdersArray of shareholders (when available)
documentsRetrieved documents with signed download URLs

​
monitor.notification

Sent when a monitored company changes status or details. 
{
  "type": "monitor.notification",
  "monitorId": "clh3k9n0x000008l63vog8wkp",
  "companyId": "932884117",
  "countryCode": "FR",
  "timestamp": "2025-09-26T14:23:45.678Z",
  "changeCategories": ["status", "address"],
  "monitorHasBeenDeactivated": false
}
Change categories:
  • status - Company status changed (active, dissolved, etc.)
  • address - Legal address changed
  • ownership - Shareholders or UBOs changed
  • financial - Capital or financial information changed
  • other - Other changes detected
  • disappeared - Company no longer found in registry

​
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).