API V2 / REFERENCE

Webhook notifications

Receive change signals in your own application.

Configure an HTTPS endpoint in your own application to receive company-change payloads. The callback belongs to the API account, so inspect its current value before replacing it.

Receiver verification

The provider returns a callback secret and signs notifications with X-GD-Signature. Verify the hex HMAC-SHA256 of the exact raw request bytes with that secret using a constant-time comparison before parsing or accepting the payload. Failed deliveries are retried a few times, checked once a minute; an exact attempt count and delivery-order guarantee are not documented.

Read the callback URL

GET/companies/watch/callback

Inspect the account’s current company-notification destination before updating it.

cURL request

curl --request GET "https://api.globaldatabase.com/v2/companies/watch/callback" \
  --header "Authorization: Token $GLOBAL_DATABASE_API_KEY"

Response

200 JSON object with callback and its signing secret. Both example values are illustrative. Keep the real secret on your server.

View JSON example

JSON response · illustrative / abbreviated

{
  "callback": "https://your-app.example/webhooks/company-changes",
  "secret": "ILLUSTRATIVE_CALLBACK_SECRET"
}

Set the callback URL

PUT/companies/watch/callback

Configure where the provider sends company change notifications.

Parameter	Location / type	Description
`callback`Required	body`string`	Your HTTPS receiver URL. Replace the example with a deployed endpoint you control.

cURL request

curl --request PUT "https://api.globaldatabase.com/v2/companies/watch/callback" \
  --header "Authorization: Token $GLOBAL_DATABASE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "callback": "https://your-app.example/webhooks/company-changes"
}'

Response

200 JSON object with callback and its signing secret. Both example values are illustrative. Keep the real secret on your server.

View JSON example

JSON response · illustrative / abbreviated

{
  "callback": "https://your-app.example/webhooks/company-changes",
  "secret": "ILLUSTRATIVE_CALLBACK_SECRET"
}

Integration notes

This is an account-level callback setting, not a per-company URL. Coordinate changes when the API account is shared.
The provider generates the secret when the callback is first set; changing the callback URL keeps the same secret. Do not send a secret in the request.

Incoming notification

POSTYour configured callback URL

This illustrative payload follows the documented notification structure. It is not a recorded event for this company.

Webhook JSON · illustrative change

{
  "company_data": {
    "id": 29707645,
    "name": "GLOBAL DATA INTELLIGENCE LIMITED",
    "registration_number": "09410808",
    "country_code": "GB",
    "date": "2026-09-14T09:30:00Z"
  },
  "field": "company.employees_number",
  "status": "UPDATE",
  "new_value": "120",
  "old_value": "100"
}

Field	Meaning
`company_data`	Company identity and the notification date. Use id for matching; retain registration_number and country_code for context.
`field`	The affected indicator, for example company.employees_number.
`status`	The sample uses UPDATE. Do not assume this matches event-history statuses such as UPDATED.
`new_value / old_value`	The changed values. Their types can vary by indicator; do not assume every value is numeric.

Recommended receiver flow

Verify X-GD-Signature over the raw request bytes with the returned callback secret, then validate the payload shape.
Check the company ID against your own enrolled companies. Keep tenant routing on your server.
Persist the notification, then queue processing. Make processing safe to repeat; the documented payload has no stable event ID.
Refresh the relevant company data and compare with your saved snapshot before showing an actionable change.
Use event-history polling to reconcile gaps. Keep original timestamps and record when your application received the notification.

These reconciliation steps are application recommendations. The provider describes retries but does not specify an exact attempt count, ordering or exactly-once delivery.

Download provider OpenAPI 3.1 Back to overview

CONTINUEErrors & usage

Based on the Global Database API v2 reference · Webhook reference rechecked 1 October 2026. Examples are illustrative or abbreviated, not live company reports.