Webhooks

Webhooks push real-time event notifications to your server as settlements progress. This is the recommended way to track settlement progress instead of polling for most states.

How webhooks work

KeyStone’s settlement engine dispatches webhooks to all platforms involved in a settlement: each time an engine run advances a settlement and leaves it in a new state, one event fires, named for the state the run ended in. Intermediate states passed through in the same run are skipped, and states written directly by on-chain events or operator actions do not emit their own event - see the event catalog for exactly what fires and how to track the rest.

Local development

During development, your server runs on localhost which KeyStone can’t reach. The KeyStone CLI solves this by forwarding webhooks to your local server:

keystone listen --forward-to http://localhost:3000/webhooks/keystone

This creates a temporary endpoint, polls for events, and forwards them to your local server in real-time. No ngrok or tunneling tools needed. See the CLI documentation for details.

Setting up a webhook endpoint

1. Register the endpoint

Create a webhook endpoint in the KeyStone Dashboard under Settings > Webhooks. You need to provide:

URL - Your HTTPS endpoint that will receive webhook deliveries
Event types - Which events to subscribe to (see patterns below)

The webhook secret is displayed once at creation time. Store it securely - you need it to verify webhook signatures. You can also register endpoints via the API:

curl -X POST https://api.keystoneos.xyz/v1/platforms/me/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-platform.com/webhooks/keystone",
    "event_types": ["settlement.*"]
  }'

const webhook = await client.webhooks.create({
  url: "https://your-platform.com/webhooks/keystone",
  eventTypes: ["settlement.*"],
});

// Store the secret securely - shown only once
console.log(webhook.secret);

webhook = await client.webhooks.create({
    "url": "https://your-platform.com/webhooks/keystone",
    "event_types": ["settlement.*"],
})

# Store the secret securely - shown only once
print(webhook.secret)

2. Event type patterns

Pattern	Matches
`*`	All events
`settlement.*`	All settlement events
`settlement.state.finalized`	Only finalization events

Webhook events

Event names are settlement.state. followed by the lowercased state name. The events that fire today:

Event	Trigger
`settlement.state.awaiting_deposits`	Compliance passed and the settlement is registered on-chain - the first event on the happy path
`settlement.state.compliance_checking`	Screening flagged a party; the settlement awaits a compliance decision
`settlement.state.compliance_cleared`	Rare: the engine halted at on-chain setup and will retry; normally skipped
`settlement.state.finalized`	Settlement executed on-chain and finalized - the success event
`settlement.state.rejected`	Compliance screening failed; settlement auto-rejected before any deposits
`test.ping`	Manual test via webhook endpoints API

There are no separate settlement.compliance.* webhook events - compliance outcomes surface through the state events above. States written directly by on-chain outcomes or operators (SETTLED, ROLLED_BACK, TIMED_OUT, MANUAL_REVIEW, and initial INSTRUCTED) currently emit no webhook of their own - track those by polling the settlement or its events endpoint; see states without their own webhook.

Webhook payload format

Every webhook delivery includes:

{
  "event": "settlement.state.compliance_cleared",
  "data": {
    "settlement_id": "018f6b2a-7c3e-7d90-b1a4-2f9c8d3e5a61",
    "state": "COMPLIANCE_CLEARED"
  }
}

The payload is intentionally minimal - it identifies the settlement and its new state. Fetch the full settlement with GET /v1/settlements/{settlement_id} when your handler needs more detail.

Verifying signatures

Every webhook delivery includes an X-Keystone-Signature header containing an HMAC-SHA256 hex digest of the request body.

# Verify manually using openssl
echo -n "$REQUEST_BODY" | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET"
# Compare output with X-Keystone-Signature header

import { KeystoneClient } from "@keystoneos/sdk";

app.post("/webhooks/keystone", (req, res) => {
  const signature = req.headers["x-keystone-signature"] as string;
  const payload = JSON.stringify(req.body);

  const isValid = client.webhooks.verifySignature(
    payload,
    signature,
    process.env.WEBHOOK_SECRET!,
  );

  if (!isValid) {
    return res.status(401).send("Invalid signature");
  }

  const event = req.body;
  console.log(`Settlement ${event.data.settlement_id} -> ${event.data.state}`);
  res.status(200).send("ok");
});

from keystoneos import KeystoneClient

@app.post("/webhooks/keystone")
async def handle_webhook(request: Request):
    payload = await request.body()
    signature = request.headers.get("x-keystone-signature", "")

    if not KeystoneClient.webhooks.verify_signature(
        payload=payload.decode(),
        signature=signature,
        secret="your-webhook-secret",
    ):
        raise HTTPException(status_code=401, detail="Invalid signature")

    event = await request.json()
    print(f"Settlement {event['data']['settlement_id']} -> {event['data']['state']}")
    return {"status": "ok"}

Always use constant-time comparison to prevent timing attacks. Never use === or == for signature verification.

Secret rotation

Rotate your webhook secret in the KeyStone Dashboard under Settings > Webhooks by clicking Rotate Secret on the endpoint, or via the API:

curl -X POST https://api.keystoneos.xyz/v1/platforms/me/webhooks/$WEBHOOK_ID/rotate-secret \
  -H "Authorization: Bearer $TOKEN"

const rotated = await client.webhooks.rotateSecret("webhook-id-...");
console.log(rotated.secret); // New secret

rotated = await client.webhooks.rotate_secret("webhook-id-...")
print(rotated.secret)  # New secret

During the 24-hour grace period:

Deliveries include both X-Keystone-Signature (new secret) and X-Keystone-Signature-Previous (old secret)
Your server should verify against both headers
After 24 hours, only the new secret is used

Testing

Send a test ping from the KeyStone Dashboard under Settings > Webhooks, or via the API:

curl -X POST https://api.keystoneos.xyz/v1/platforms/me/webhooks/$WEBHOOK_ID/test \
  -H "Authorization: Bearer $TOKEN"

await client.webhooks.test("webhook-id-...");

await client.webhooks.test("webhook-id-...")

Best practices

Return 200 quickly - Process webhooks asynchronously. Return a 200 status immediately and handle the event in a background job.
Handle duplicates - Webhooks may be delivered more than once. Use the settlement ID plus state to make your handler idempotent.
Verify signatures - Always verify the HMAC signature before processing. Reject unsigned or invalid requests.
Monitor delivery logs - Check delivery logs in the KeyStone Dashboard or via the API:

curl https://api.keystoneos.xyz/v1/platforms/me/webhooks/$WEBHOOK_ID/deliveries \
  -H "Authorization: Bearer $TOKEN"

const deliveries = await client.webhooks.deliveries("webhook-id-...");

for (const delivery of deliveries.items) {
  console.log(`${delivery.event} - ${delivery.statusCode}`);
}

deliveries = await client.webhooks.deliveries("webhook-id-...")

for delivery in deliveries.items:
    print(f"{delivery.event} - {delivery.status_code}")

Retry policy

Failed deliveries (non-2xx response or timeout) are retried up to 3 times in quick succession with short, jittered backoff (a Retry-After header is honored on 429 responses). After that the delivery is marked as failed in the delivery log - there is no delayed redelivery queue, so reconcile missed events by fetching the settlement’s current state.

Webhook Event Catalog

See every event type with exact payloads and handler examples.

CLI Webhook Forwarding

Forward webhooks to localhost during development.

Getting Started

Core Concepts

Guides

Smart Contracts

How webhooks work

Local development

Setting up a webhook endpoint

1. Register the endpoint

2. Event type patterns

Webhook events

Webhook payload format

Verifying signatures

Secret rotation

Testing

Best practices

Retry policy

Webhook Event Catalog

CLI Webhook Forwarding

​How webhooks work

​Local development

​Setting up a webhook endpoint

​1. Register the endpoint

​2. Event type patterns

​Webhook events

​Webhook payload format

​Verifying signatures

​Secret rotation

​Testing

​Best practices

​Retry policy

Webhook Event Catalog

CLI Webhook Forwarding

How webhooks work

Local development

Setting up a webhook endpoint

1. Register the endpoint

2. Event type patterns

Webhook events

Webhook payload format

Verifying signatures

Secret rotation

Testing

Best practices

Retry policy