Webhooks

Webhooks let Grand push you a notification the moment a company profile changes, so you don't have to poll GET /v1/profile/{companyNumber} on a schedule. Register an HTTPS URL, and Grand sends a small signed event whenever a profile you care about changes — you then re-fetch the profile to get the detail.

How it works

flowchart LR
    A[You pull a profile
GET /v1/profile/…] --> B[Grand watches that company]
    B --> C{Profile changes}
    C --> D[Grand POSTs a signed
event to your URL]
    D --> E[You verify the signature
and re-fetch the profile]

You subscribe — register an HTTPS endpoint (see Managing subscriptions).
You pull profiles — every company you fetch via GET /v1/profile/{companyNumber} is automatically watched for you. You only receive webhooks for companies you've pulled — there is nothing extra to configure per company.
Grand delivers — when a watched company's profile changes, Grand sends a signed POST to your endpoint.
You react — verify the signature, then re-fetch the profile for the updated data.

The webhook payload is intentionally minimal — it tells you what changed (type + block) and which company, not the new values. Always re-fetch the profile for the current data. This keeps you working from a single source of truth and the payload stable over time.

Events at a glance

Event `type`	Fired when
`profile.changed`	A profile block changes — trading status, risk of failure, filing behaviour, credit capacity, or company overview.
`profile.early_signal.detected`	A new early-warning signal appears on a company.
`profile.early_signal.updated`	An existing early signal changes state (e.g. superseded or expired).

See Events & payloads for the full payload contract and the block values.

What a webhook looks like

Grand POSTs JSON to your endpoint with an x-grand-signature header:

POST /your-endpoint HTTP/1.1
Content-Type: application/json
x-grand-signature: YoPzTaaY+ACzhxpny9WLXQFFV8kppPZcRu2Ixf0diwY=

{
  "type": "profile.changed",
  "apiVersion": "v1",
  "occurredAt": "2026-06-30T19:40:00Z",
  "idempotencyKey": "PROFILE_CHANGED:SC855307:ACTIVE_TO_CEASED:20260630",
  "block": "tradingStatus",
  "data": { "jurisdiction": "GB", "companyNumber": "SC855307" }
}

Managing subscriptions

Create and manage webhook subscriptions from your Grand workspace — add one or more HTTPS endpoint URLs. Each subscription has:

A name and URL (must be https://).
A signing secret — used to verify the x-grand-signature on every delivery. It's available on the subscription at any time, so you can fetch it when configuring your receiver.
A status (ACTIVE).

Treat the signing secret like a password — store it in a secrets manager, never in source control or a browser. Anyone with it can forge signatures for that subscription.

Next steps

Every event type, the payload contract, and what each `block` maps to. Verify `x-grand-signature` so you only trust genuine Grand events. Retries, idempotency, ordering, and how to respond. The `GET /v1/profile/{companyNumber}` endpoint you re-fetch after a webhook.

Events & payloads