Webhooks

A webhook lets the API push events to your systems as they happen, so you do not have to poll for every change. You register a webhook endpoint, choose which events it should receive, and the API POSTs a small JSON message to that endpoint whenever a matching event occurs. This is the natural way to learn that a case has finished building, that a new AML match has appeared during ongoing monitoring, or that a document has been uploaded. For the concepts and the full contract, see the Guide and the API Reference.

Webhooks complement polling rather than replace it. Polling is still the simplest way to wait for a single case to become ready in a short-lived script (see Poll until ready); webhooks are the better fit when you run at scale, monitor many cases over time, or want events delivered without a polling loop.

The events

There are ten event types. Each webhook message names the event in its eventType field, and you subscribe a URL to whichever events you care about.

Payload

Every delivery is an HTTP POST with a JSON body of two top-level keys: the eventType and a body object.

{
  "eventType": "CaseReady",
  "body": {
    "caseType": 1,
    "caseCommonId": "CR-P-2481",
    "caseName": "Cropwell Bishop Creamery Limited",
    "caseUrl": "https://workspace.knowyourcustomer.dev/cases/CR-P-2481",
    "message": "The case has finished building and is ready to read.",
    "caseProperties": {}
  }
}

The body is a reference to the case, not a full copy of it. It tells you what happened and to which case; you then call the API (or open the caseUrl) to read the full, current data. Common fields you can rely on:

• caseType is 1 for a company or entity and 2 for an individual.
• caseCommonId is the case identifier. Treat it as a string: it may be a plain number or a prefixed common id such as CR-P-2481.
• caseName, caseUrl, and a human-readable message.
• caseProperties is an object of any custom properties on the case, and can be empty.
• Event-specific extras as listed in the table above.

Registering a webhook

Each environment sends to a single webhook endpoint. In a regular Know Your Customer environment you set it in the admin console under Admin > Integrations (your environment URL followed by /app/Admin/Integrations): enter the URL that should receive events, and save. The sandbox additionally lets you manage the webhook from the Workspace or over its API, described below, so you can script your test setup.

In the Workspace (sandbox)

Open workspace.knowyourcustomer.dev, connect with your sandbox credentials, and go to Webhooks. Set your webhook URL, tick the events you want, and save. The same screen shows the delivery log (see Inspecting deliveries).

Over the API (sandbox)

Create a subscription by POSTing a URL and the list of events to /sandbox/webhooks/subscriptions with your bearer token. The request body uses event_types; each must be one of the ten names above.

curl -X POST https://api.knowyourcustomer.dev/sandbox/webhooks/subscriptions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-endpoint.example.com/kyc-webhook",
    "event_types": ["CaseReady", "AmlMatch", "CaseClosed"],
    "active": true
  }'

The response returns the created subscription, including its id and the eventTypes it is subscribed to. List with GET /sandbox/webhooks/subscriptions, update with PATCH /sandbox/webhooks/subscriptions/{id} (change the URL, the events, or set active to false to pause it), and remove with DELETE /sandbox/webhooks/subscriptions/{id}. Subscriptions belong to your tenant and are cleared when you reset the tenant, so a clean test run starts from an empty slate.

Delivery, retries, and failure

Each event is delivered as a JSON POST to your URL. Your endpoint should respond with any 2xx status to acknowledge receipt; the body of your response is ignored. If your endpoint returns a non-2xx status or cannot be reached, the delivery is retried.

• Retries: a failing delivery is retried up to ten times, with a growing backoff between attempts.
• Blocking: if all ten attempts fail, that URL is blocked for one hour to protect the delivery pipeline. Events that occur during the blocking window are dropped rather than queued, and delivery resumes for new events once the hour has passed.
• Acknowledge fast: respond 2xx as soon as you have safely received the message, then do your processing asynchronously. Do not hold the connection open for long-running work.

Security

In the sandbox, deliveries are sent without an authentication header or signature, matching the standard product. Treat your webhook URL as a secret: use an https endpoint, keep the URL private, and do not encode anything sensitive in it. If you want to correlate a delivery to a case, use the caseCommonId in the payload and confirm against the API.

Production deployments with stricter requirements can arrange additional secured delivery (for example signed or encrypted payloads) as part of commercial onboarding. That is not part of the free sandbox.

Inspecting deliveries

Every attempt is recorded so you can debug your receiver without guesswork, which is something the raw production pipeline does not expose to you. The Workspace Webhooks screen shows each delivery with its event type, the exact JSON that was sent, the HTTP status your endpoint returned, and whether it was delivered, is retrying, is blocked, or was dropped. You can filter by subscription or by case.

The same log is available over the API at GET /sandbox/webhooks/deliveries, with optional subscription_id and case_common_id filters. Use it while you are wiring up a handler to confirm exactly what you received and, when something fails, to see why.

Try it in the sandbox

The quickest way to see webhooks working end to end:

1. Stand up a receiver. For a quick test, a throwaway endpoint from a request-inspection service (for example webhook.site or a small local server behind a tunnel) is enough to see the payloads arrive.
2. Register it for CaseCreated and CaseReady, either in the Workspace or with the curl above.
3. Create a case (see the Quickstart). You should receive CaseCreated shortly after, then CaseReady once the case finishes building. Note that CaseReady arrives even if you never poll the case yourself.
4. Check your receiver, and cross-check the delivery log in the Workspace or at /sandbox/webhooks/deliveries.