Webhook Event Catalog

This page is a complete reference for the webhook events that KeyStone dispatches. For setup instructions, signature verification, and best practices, see the Webhooks guide.

Payload structure

Every webhook delivery follows the same envelope format:

{
  "event": "settlement.state.awaiting_deposits",
  "data": {
    "settlement_id": "550e8400-e29b-41d4-a716-446655440000",
    "state": "AWAITING_DEPOSITS"
  }
}

Field	Type	Description
`event`	string	Dot-delimited event name (e.g. `settlement.state.finalized`)
`data.settlement_id`	string (UUID)	The settlement this event relates to
`data.state`	string	The settlement state that triggered the event

The payload is intentionally minimal. When your handler needs more context (parties, legs, timestamps, transitions), fetch the settlement with GET /v1/settlements/{settlement_id} or its event history with GET /v1/settlements/{settlement_id}/events.

When webhooks fire

Every settlement state transition emits an event, named settlement.state. plus the lowercased state name. There is no filtering on KeyStone’s side beyond the patterns you subscribe to. This holds because every state transition goes through one function, which enqueues the webhook in the same database transaction as the state change. A transition cannot be committed without its announcement being committed alongside it. The one state that is not reached by a transition is INSTRUCTED, which is written when the settlement row is created. It emits no webhook. The response to your instruction or initiation call carries the settlement_id, so there is nothing to wait for. Three consequences worth designing around:

Intermediate states are not skipped. A single engine run that walks INSTRUCTED to COMPLIANCE_CHECKING to COMPLIANCE_CLEARED to AWAITING_DEPOSITS emits four events, not one. Order is guaranteed by the sequence of transitions, but delivery order is not: the delivery worker sends independently, and retries can reorder. Use data.state rather than arrival order to decide where a settlement is.
The source of a transition makes no difference. Engine walks, on-chain event application, compliance decisions, operator actions, rollbacks and timeouts all emit identically. SETTLED, ROLLED_BACK and TIMED_OUT reach you as webhooks like any other state.
Subscribers are matched at enqueue time. The endpoints registered when the transition commits are the ones that receive it. An endpoint added a second later does not get that event.

Deliveries are enqueued once per matching endpoint. Where two platforms share a settlement, each receives the event against its own endpoints, and an endpoint subscribed under more than one environment is still enqueued only once per transition.

Events you will receive

`settlement.state.compliance_checking`

Fired when the settlement enters screening. This is the first event you receive for a settlement: the preceding INSTRUCTED state is set at creation rather than by a transition, and emits nothing. Every settlement that proceeds past creation passes through this state, so you receive this event on the happy path as well as when a party is flagged. Where screening flags a party, the settlement parks here awaiting a manual compliance decision and the next event does not follow immediately.

{
  "event": "settlement.state.compliance_checking",
  "data": {
    "settlement_id": "550e8400-e29b-41d4-a716-446655440000",
    "state": "COMPLIANCE_CHECKING"
  }
}

What to do: Route the settlement to your compliance team. Submit the outcome with POST /v1/settlements/{settlement_id}/compliance-decision - approving lets the settlement continue (you will receive awaiting_deposits when it registers on-chain); rejecting ends it in REJECTED.

`settlement.state.awaiting_deposits`

Fired when compliance has passed and the settlement is registered on-chain, ready for escrow deposits.

{
  "event": "settlement.state.awaiting_deposits",
  "data": {
    "settlement_id": "550e8400-e29b-41d4-a716-446655440000",
    "state": "AWAITING_DEPOSITS"
  }
}

What to do: This is the key action event. Trigger your deposit workflow - instruct your custody provider (e.g. Fireblocks) to send assets to the escrow address, or notify the trader that a deposit is required.

`settlement.state.rejected`

Fired when compliance screening fails outright and the settlement is auto-rejected before any deposits. Nothing is locked on-chain at this point. (A settlement rejected by a manual compliance decision reaches the same REJECTED state - poll or check the settlement after submitting a decision.)

{
  "event": "settlement.state.rejected",
  "data": {
    "settlement_id": "550e8400-e29b-41d4-a716-446655440000",
    "state": "REJECTED"
  }
}

What to do: Notify the involved parties that the settlement cannot proceed. Do not expose the specific compliance failure reason to end users - log it internally for your compliance team. This is a terminal state.

`settlement.state.compliance_cleared`

Fired when every party has cleared screening, before on-chain registration is attempted. You receive this on the happy path, normally moments before awaiting_deposits.

What to do: Informational. If awaiting_deposits does not follow, on-chain registration is being retried; a settlement that stays here is one to investigate.

`settlement.state.settled`

Fired when the contract has executed on-chain and KeyStone has observed the SettlementExecuted event. This is the delivery signal: at this point every leg has paid out to its recorded recipient and the transfer is irreversible.

{
  "event": "settlement.state.settled",
  "data": {
    "settlement_id": "550e8400-e29b-41d4-a716-446655440000",
    "state": "SETTLED"
  }
}

What to do: This is the event to act on for delivery. finalized follows once close-out bookkeeping completes and adds no new economic information.

`settlement.state.finalized`

Fired when the settlement has executed on-chain and the record is finalized. This is the terminal success state.

{
  "event": "settlement.state.finalized",
  "data": {
    "settlement_id": "550e8400-e29b-41d4-a716-446655440000",
    "state": "FINALIZED"
  }
}

What to do: Update your OMS to mark the trade as settled. Notify the trader that their assets have been delivered. This is a terminal state.

`settlement.state.manual_review`

Fired when a settlement is parked in MANUAL_REVIEW for operator attention: an engine action failed after compliance cleared, the settlement went stale past its deadline, or an operator escalated it. You will not see this on the happy path; it indicates a settlement needs manual intervention.

{
  "event": "settlement.state.manual_review",
  "data": {
    "settlement_id": "550e8400-e29b-41d4-a716-446655440000",
    "state": "MANUAL_REVIEW"
  }
}

What to do: Alert your operations team. The settlement is parked and an operator resolves it (which drives it to ROLLED_BACK or TIMED_OUT); poll GET /v1/settlements/{id} to follow the outcome.

`settlement.state.rolled_back`

Fired when the settlement was aborted on-chain and KeyStone has observed the SettlementAborted event. No leg pays out. Every deposited leg becomes claimable by the address that deposited it.

{
  "event": "settlement.state.rolled_back",
  "data": {
    "settlement_id": "550e8400-e29b-41d4-a716-446655440000",
    "state": "ROLLED_BACK"
  }
}

What to do: Release the trade in your OMS and start your refund flow. Each funded leg is refunded by its own call, and the funds always return to the address that deposited them. See escrow deposits.

`settlement.state.timed_out`

Fired when the settlement passed its deadline without executing, and a timeout claim moved it to a terminal state on-chain. That covers both the unfunded case and a fully funded settlement whose compliance gate never cleared in time. Refunds work exactly as for rolled_back.

{
  "event": "settlement.state.timed_out",
  "data": {
    "settlement_id": "550e8400-e29b-41d4-a716-446655440000",
    "state": "TIMED_OUT"
  }
}

What to do: Same as rolled_back. If your side was the one that funded, claim your refund; if it was not, no action is needed on-chain.

`test.ping`

Fired when you test a webhook endpoint via the Dashboard or the API. Used to verify your endpoint is reachable and correctly verifying signatures.

{
  "event": "test.ping",
  "data": {
    "message": "Webhook test from KeyStone"
  }
}

What to do: Return a 200 response. Note the data object carries no settlement fields - handle test.ping before any settlement-specific parsing.

Complete event list

The settlement.state.<state> namespace covers every state in the settlement state machine. Every state reached by a transition is delivered; INSTRUCTED is set at creation and is the one state with no event.

Event	State	Terminal	Meaning
none	`INSTRUCTED`		Settlement created. Set at creation, not by a transition, so no webhook fires. The creation response carries the `settlement_id`.
`settlement.state.compliance_checking`	`COMPLIANCE_CHECKING`		Screening in progress, or parked on a flag
`settlement.state.compliance_cleared`	`COMPLIANCE_CLEARED`		Every party cleared
`settlement.state.awaiting_deposits`	`AWAITING_DEPOSITS`		Registered on-chain, ready to fund
`settlement.state.settled`	`SETTLED`		Executed on-chain, legs delivered
`settlement.state.finalized`	`FINALIZED`	yes	Close-out complete
`settlement.state.rejected`	`REJECTED`	yes	Compliance decision rejected the settlement
`settlement.state.rolled_back`	`ROLLED_BACK`	yes	Aborted on-chain, refunds open
`settlement.state.timed_out`	`TIMED_OUT`	yes	Deadline passed without executing, refunds open
`settlement.state.manual_review`	`MANUAL_REVIEW`		Parked for an operator
`test.ping`			Endpoint test, carries no settlement fields

Subscribe to settlement.state.* unless you have a reason not to. Filtering to a narrow set means a state you did not anticipate passes silently, and the states worth reacting to hardest are the failure terminals.

Event filtering

When registering a webhook endpoint, you specify which events to receive using glob-style patterns.

Pattern	What it matches
`*`	All events (settlement state and test)
`settlement.*`	All settlement events
`settlement.state.*`	All state transition events
`settlement.state.finalized`	Only the finalized event
`test.*`	Only test events

You can subscribe to multiple patterns per endpoint:

{
  "url": "https://your-platform.com/webhooks/keystone",
  "events": [
    "settlement.state.awaiting_deposits",
    "settlement.state.finalized",
    "settlement.state.rejected",
    "settlement.state.compliance_checking"
  ]
}

The subscription field is events. Patterns are matched with glob semantics, and a pattern that matches no real event is accepted but simply never fires. If you omit events, it defaults to ["*"]. Subscribing to settlement.state.* is the safe explicit default: you receive every event that fires today and automatically pick up any states that gain webhooks later.An endpoint accepts at most 50 patterns, each at most 100 characters. Both ceilings sit well above the event namespace on this page, so they only bite on generated pattern lists.

Signature verification

Every delivery includes an X-Keystone-Signature header carrying a timestamped HMAC-SHA256 signature (t=<unix_seconds>,v1=<hex digest>, signed over "{t}." + raw body) and an X-Keystone-Delivery-Id header for deduplicating retries and replays. See Verifying signatures in the Webhooks guide for the full scheme, verification snippets in Python and Node.js, the replay-tolerance window, and rotation-grace handling - that section is the single source for signature mechanics.

Always use constant-time comparison (crypto.timingSafeEqual in Node.js, hmac.compare_digest in Python) to prevent timing attacks. Never compare signatures with === or ==.

Secret rotation

When you rotate a webhook secret, KeyStone provides a 24-hour grace period where both the old and new secrets are valid. During this window:

X-Keystone-Signature is signed with the new secret
X-Keystone-Signature-Previous is signed with the old secret

Your verification logic should accept a delivery when EITHER header verifies (both use the timestamped scheme from the Webhooks guide, the previous header signed with the old secret). After 24 hours, the old secret is discarded and only X-Keystone-Signature is sent.

Retry behavior

Deliveries are at-least-once: a failed attempt (anything but a 2xx, including a 3xx, or a timeout) is retried on a growing backoff ladder (1m, 5m, 30m, 2h, 6h, 12h, 24h) and marked dead after 8 total attempts. Every attempt is visible in the delivery logs, and dead or already-delivered events can be re-sent with the replay endpoints - deduplicate on X-Keystone-Delivery-Id, which stays stable across retries and replays.

Your endpoint must respond within 10 seconds. If processing takes longer, return 200 immediately and handle the event asynchronously in a background job.

Idempotency

The same event may be delivered more than once. Your webhook handler must be idempotent. Recommended patterns:

Check current state before acting. If you receive settlement.state.finalized but the trade is already marked as settled in your system, skip processing.
Use the settlement ID plus state as a deduplication key. Track which settlement/state combinations you have already processed.
Make downstream calls idempotent. If your handler triggers a transfer or notification, ensure the downstream system also handles duplicates.

app.post("/webhooks/keystone", async (req: Request, res: Response) => {
  const { event, data } = req.body;

  // Deduplicate: check if we already processed this state for this settlement
  const key = `${data.settlement_id}:${data.state}`;
  const alreadyProcessed = await redis.get(`webhook:processed:${key}`);

  if (alreadyProcessed) {
    return res.status(200).send("ok"); // Already handled, return success
  }

  // Process the event
  await handleEvent(event, data);

  // Mark as processed (TTL of 7 days)
  await redis.set(`webhook:processed:${key}`, "1", "EX", 604800);

  res.status(200).send("ok");
});

Full handler example

A complete webhook handler in TypeScript that covers signature verification, idempotency, and event routing:

import crypto from "crypto";
import type { Request, Response } from "express";

const WEBHOOK_SECRET = process.env.KEYSTONE_WEBHOOK_SECRET!;

function verifySignature(body: string, signature: string): boolean {
  const expected = crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected),
  );
}

app.post("/webhooks/keystone", async (req: Request, res: Response) => {
  // 1. Verify signature
  const signature = req.headers["x-keystone-signature"] as string;
  if (!signature || !verifySignature(JSON.stringify(req.body), signature)) {
    return res.status(401).send("Invalid signature");
  }

  // 2. Return 200 immediately
  res.status(200).send("ok");

  // 3. Process asynchronously
  const { event, data } = req.body;

  switch (event) {
    case "settlement.state.awaiting_deposits":
      await triggerDepositWorkflow(data.settlement_id);
      break;

    case "settlement.state.compliance_checking":
      await routeToComplianceReview(data.settlement_id);
      break;

    case "settlement.state.finalized":
      await markTradeAsSettled(data.settlement_id);
      await notifyTrader(data.settlement_id, "Your settlement is complete.");
      break;

    case "settlement.state.rejected":
      await markTradeAsFailed(data.settlement_id);
      await escalateToCompliance(data.settlement_id);
      break;

    case "test.ping":
      console.log("Webhook test received");
      break;

    default:
      // Future states may gain webhooks - log and fetch the settlement.
      console.log(`Unhandled event: ${event}`);
  }
});

For SDK-based webhook handling with built-in signature verification, see the TypeScript SDK webhooks guide or Python SDK webhooks guide.

Getting Started

Core Concepts

Guides

Smart Contracts

Webhook Event Catalog

Payload structure

When webhooks fire

Events you will receive

`settlement.state.compliance_checking`

`settlement.state.awaiting_deposits`

`settlement.state.rejected`

`settlement.state.compliance_cleared`

`settlement.state.settled`

`settlement.state.finalized`

`settlement.state.manual_review`

`settlement.state.rolled_back`

`settlement.state.timed_out`

`test.ping`

Complete event list

Event filtering

Signature verification

Secret rotation

Retry behavior

Idempotency

Full handler example

​Payload structure

​When webhooks fire

​Events you will receive

​settlement.state.compliance_checking

​settlement.state.awaiting_deposits

​settlement.state.rejected

​settlement.state.compliance_cleared

​settlement.state.settled

​settlement.state.finalized

​settlement.state.manual_review

​settlement.state.rolled_back

​settlement.state.timed_out

​test.ping

​Complete event list

​Event filtering

​Signature verification

​Secret rotation

​Retry behavior

​Idempotency

​Full handler example

Payload structure

When webhooks fire

Events you will receive

`settlement.state.compliance_checking`

`settlement.state.awaiting_deposits`

`settlement.state.rejected`

`settlement.state.compliance_cleared`

`settlement.state.settled`

`settlement.state.finalized`

`settlement.state.manual_review`

`settlement.state.rolled_back`

`settlement.state.timed_out`

`test.ping`

Complete event list

Event filtering

Signature verification

Secret rotation

Retry behavior

Idempotency

Full handler example