Webhooks

Securely receiving asynchronous updates for company data and monitoring

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.

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",
    "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.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
}

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

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