Webhooks

Topograph uses webhooks to notify you about asynchronous events:

Data Retrieval: When company data or documents are ready (verification data).
Monitoring: When a monitored company changes (Monitoring API).

Configuration

You configure webhooks in the Topograph Dashboard under Developers > Webhooks.

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 a standard webhook signature verification library or your own HMAC verification code to verify these headers.

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

const evt = verifyWebhookSignature(payload, headers, secret);

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 you get by calling GET /v2/company/{requestId}, plus an added type field.

{
  "type": "company.updated",
  "request": {
    "companyId": "932884117",
    "countryCode": "FR",
    "requestId": "86c082a6-c9a0-4243-87d8-7ae18f0ee13a",
    "version": 7,
    "dataStatus": {
      "dataPoints": {
        "company": { "status": "succeeded", "authoritative": true },
        "availableDocuments": { "status": "in_progress" }
      }
    }
  },
  "company": {
    "id": "932884117",
    "countryCode": "FR",
    "legalName": "TOPOGRAPH",
    "status": {
      "localName": "Immatriculée",
      "active": true,
      "statusDetails": {
        "status": "ACTIVE"
      }
    },
    "legalAddress": {
      "addressLine1": "123 Rue Example",
      "city": "Paris",
      "postalCode": "75001",
      "countryCode": "FR"
    }
  },
  "documents": {
    "tradeRegisterExtract": {
      "id": "1c932de4-4610-5506-b48d-4e62529d58e8",
      "name": "Extrait Kbis",
      "format": "pdf",
      "url": "https://..."
    }
  }
}

Key fields:

Field	Description
`type`	Event type identifier (`company.updated`)
`request.requestId`	Unique identifier to correlate webhooks with your original request
`request.version`	Monotonic snapshot version for this `requestId`. A higher value is a newer snapshot. Use it to discard stale, out-of-order deliveries (see Ordering and duplicate delivery).
`request.metadata`	The key-value pairs you provided when creating the request, echoed back so you can map the webhook to your internal records
`request.dataStatus`	Status of each data point (`succeeded`, `in_progress`, `enriching`, `failed`). `enriching` means the datapoint is in progress with an intermediate AI enrichment result available.
`company`	Core company information
`ultimateBeneficialOwners`	Array of beneficial owners (when available)
`legalRepresentatives`	Array of legal representatives (when available)
`shareholders`	Array of shareholders (when available)
`documents`	Retrieved 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,
  "metadata": {
    "caseId": "case-12345"
  }
}

metadata echoes the key-value pairs you set when creating the monitor (POST /v2/monitors). Use it to map the notification back to your internal records. The field is only present when the monitor has metadata. Change categories:

status - Company status changed (active, dissolved, etc.)
address - Legal address changed
ownership - Shareholders or UBOs changed
financial - Capital or financial information changed
legalRepresentatives - Legal representatives or directors changed
other - Other changes detected
disappeared - Company no longer found in register

Testing it: the portal’s sample payload carries no real monitor id and no metadata, so it can’t exercise an integration that routes on either. To receive a genuine event on demand, use Send Test Notification on a monitor’s page in the dashboard, or POST /v2/monitors/{monitorId}/test-notification. See Monitoring.

Ordering and duplicate delivery

Webhooks for the same requestId are not guaranteed to arrive in order, and the same event can be delivered more than once due to retries. A company.updated that fails on its first delivery is retried later and can land after a newer one that succeeded immediately. Two rules keep your data correct:

Each payload is a full snapshot, identical to what GET /v2/company/{requestId} returned at the time it was sent. Merge it into your store per data point. Do not blindly replace your record based on arrival order, or a late in_progress delivery can overwrite newer data.
Use request.version to reject stale updates. It increases every time the snapshot changes for a requestId. Track the highest version you have applied per requestId and ignore any webhook whose version is lower than or equal to it. The late in_progress delivery carries a lower version than the final one, so this drops it.

request.version is scoped to a single requestId. Do not compare it across different requests.

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

Getting Started

Integration Guides

Core Features

Behavior & Operations

Configuration

Verification (Security)

1. Get your signing secret

2. Verify the signature

Event Types

`company.updated`

`monitor.notification`

Ordering and duplicate delivery

Retry Policy

​Configuration

​Verification (Security)

​1. Get your signing secret

​2. Verify the signature

​Event Types

​company.updated

​monitor.notification

​Ordering and duplicate delivery

​Retry Policy

Configuration

Verification (Security)

1. Get your signing secret

2. Verify the signature

Event Types

`company.updated`

`monitor.notification`

Ordering and duplicate delivery

Retry Policy