Suitability webhooks

Every time the verificationStatus of one of your investors’ suitability or DLT test changes, Securitize sends one POST to your account’s webhook endpoint. You receive it for every investor of your account, including the ones you have limited access to.

Event	Announces a change of	Read it with
`investor.suitability.updated`	`verificationStatus` of the suitability	`GET /investors/{investorId}/suitability`
`investor.dlt_test.updated`	`verificationStatus` of the DLT test	`GET /investors/{investorId}/dlt-test`

Suitability webhooks are available in sandbox. Ask your Securitize contact for production.

POST https://your.endpoint.invalid/securitize/webhooks
content-type: application/json
svix-id: msg_3KyR8vNqT2cWb6LmZ0pDf4HsJ1a
svix-timestamp: 1792675200
svix-signature: v1,dGhpcyBpcyBub3QgYSByZWFsIHNpZ25hdHVyZSwgb25seSBhbiBleGFtcGxl

{
  "schemaVersion": "1.0",
  "sourceEventId": "suit_8c2f4a1e9b7d40c3a6e5f1b2d9c07e4a",
  "eventType": "investor.suitability.updated",
  "occurredAt": "2026-10-22T10:00:00.000Z",
  "data": {
    "investorId": "6ace745fab21fd6924a19beb",
    "externalInvestorId": "your-investor-0001",
    "verificationStatus": "verified"
  }
}

data.investorId is the investorId the create returned, and data.externalInvestorId your own id. data.verificationStatus is the new verdict, with the same values as the GET: none, processing, verified, rejected. Every field is in the API reference: suitability and DLT test.

Webhooks

How every Securitize webhook is delivered: the headers, verifying the signature, acknowledging within 10 seconds, retries and your endpoint. Start there, then come back for what is specific to suitability.

When it is sent

The verdict can change outside your own calls, and those are the changes the webhook is for:

Securitize’s compliance team sets a verdict after a review, including processing and rejected. That includes the review of an individual’s suitability, full or compact, that answered processing.
The investor or another partner completes the suitability or passes the DLT test. The suitability is sent once for every channel, so a completion by someone else changes the verdict you read.
Your own call changes the verdict too, and its response already tells you the new value; the webhook follows it.

The DLT test event announces the verdict, not the attempts: a failed attempt or a locked test sends nothing, because the verdict stays as it was. The DLT test verdict becomes verified once the test is passed and the suitability is complete, in either order, so one completion can send both events.

Apply it

Delivery is at least once and can be out of order: retries repeat an event, and two quick changes can arrive in either order. Each event is the verdict at occurredAt, not a step from one value to another.

Rule	Why
Deduplicate on `sourceEventId`	A retry carries the same id; every change gets a new one. Store the ids you have applied and skip a repeat
Keep the latest by `occurredAt` per investor and event type	The suitability and the DLT test verdicts change on their own; an event older than the verdict you hold for that resource is a late delivery: ignore it
Read the verdict before you act on it	Before requesting a whitelisting or telling the investor the outcome, confirm with the GET of that resource: it always answers the current verdict
Accept event types you do not handle	Your endpoint receives every event your account is sent. Answer `2xx` to a type you do not use, or ask your Securitize contact to filter your endpoint’s types

Past suitability webhooks stay readable for 90 days and failed deliveries can be resent, through the webhook events routes shared by every API (Replay and recover). The list there carries every type your account is sent, also the ones your endpoint filters out.

Get started

Guides

Concepts

Help

API reference

Webhooks

When it is sent

Apply it