Receive webhooks

Securitize sends one POST per corporate action event to your account’s webhook endpoint. The body is the event envelope: what happened, to which object, at which version, with the object’s full state in data.

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 corporate actions.

A delivery that failed stays readable and resendable for 90 days (Replay and recover, at the webhooks base URL shared by every API).

Apply it exactly once

Delivery is at least once and can be out of order: retries repeat an event, and deliveries run in parallel, so a later version can arrive before an earlier one. Three rules make the handler correct whatever arrives:

Rule	On what	Why
Deduplicate on `sourceEventId`	Every event	A retry carries the same id. Store the ids you have applied (90 days is enough) and skip a repeat
Apply by `version` per object	`objectId`	Keep the highest `version` you have seen for each corporate action, restriction or token; ignore an event with a lower or equal one
Order by `sequence` per stream	`stream.id`	Within one token stream `sequence` strictly increases. Gaps are normal: you receive only the events of your tokens

data is the whole object: replace what you hold, never merge. changedFields is there for your own diffing and notifications, not for applying the change. A handler that follows the three rules:

export async function handle(event) {
  // 1. Deduplicate.
  if (await store.hasEvent(event.sourceEventId)) return;

  // 2. Apply by version, per object.
  const current = await store.get(event.objectType, event.objectId);
  if (!current || event.version > current.version) {
    await store.put(event.objectType, event.objectId, event.data, event.version);
    await react(event); // your side effects: stop trading, notify, schedule
  }

  await store.markEvent(event.sourceEventId);
}

Branch on objectType to know what data is, and on eventType to know what happened: a corporate action (ca.action.*), a restriction (ca.restriction.*) or a token (ca.token.updated). Treat an eventType you do not know as “something changed on this object” and still apply data by version.

React to what matters

Most events need no action beyond storing them. The ones that do:

Event	Act on
`ca.restriction.added`, `ca.restriction.updated`	`data.restrictionType` and `data.scope`: stop trading the affected tokens. Confirm with `GET /tokens/{tokenId}/status` if in doubt
`ca.restriction.removed`	Resume: the only signal that a restriction has ended
`ca.action.created`, `ca.action.updated`	`data.venueActions`: `tradingStop`, `poolMode`, `lpExitDeadline`, `displayToHolders`, `transferFlowRequired`
`ca.action.status_changed` to `ELECTION_OPEN`	`data.options`: show holders their choices, with `responseDeadline`
`ca.action.completed`	`data.settlement`: the distribution contracts and transactions to reconcile against on chain
`ca.action.cancelled`, `ca.action.postponed`	Withdraw or update what you show holders

Your endpoint

By default the endpoint receives all eleven corporate action event types, next to the events of any other Securitize API your account uses; your Securitize contact can limit it to some. If you suspect a gap, check the event list against what you stored.

Get started

Guides

Concepts

Help

API reference

Webhooks

Apply it exactly once

React to what matters

Your endpoint