Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.keystoneos.xyz/llms.txt

Use this file to discover all available pages before exploring further.

Webhooks push real-time event notifications to your server whenever a settlement changes state. This is the recommended way to track settlement progress instead of polling.

​
How webhooks work

When a settlement changes state on-chain, KeyStone dispatches webhooks to all platforms involved in the settlement. Webhooks are delivered within seconds of the on-chain event.

​
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.*"]
  }'

​
2. Event type patterns

PatternMatches
*All events
settlement.*All settlement events
settlement.state.finalizedOnly finalization events

​
Webhook events

EventTrigger
settlement.state.instructedSettlement created on-chain
settlement.state.compliance_checkingCompliance screening started
settlement.state.compliance_clearedAll compliance checks passed
settlement.state.awaiting_depositsReady for escrow deposits
settlement.state.executing_swapAll deposits confirmed, auto-executing
settlement.state.finalizedSettlement complete, assets delivered
settlement.state.rolled_backSettlement rolled back, deposits returned
settlement.state.timed_outSettlement timed out, deposits returned
settlement.compliance.clearedCompliance screening passed
settlement.compliance.failedCompliance screening failed
settlement.compliance.flaggedCompliance flagged for manual review
test.pingManual test via webhook endpoints API

​
Webhook payload format

Every webhook delivery includes: 
{
  "event": "settlement.state.compliance_cleared",
  "data": {
    "settlement_id": "stl-...",
    "state": "COMPLIANCE_CLEARED",
    "previous_state": "COMPLIANCE_CHECKING",
    "settlement_type": "single_platform",
    "timestamp": "2026-03-16T12:00:00Z"
  }
}

​
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
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"
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"

​
Best practices

  1. Return 200 quickly - Process webhooks asynchronously. Return a 200 status immediately and handle the event in a background job.
  2. Handle duplicates - Webhooks may be delivered more than once. Use the event ID or settlement state to make your handler idempotent.
  3. Verify signatures - Always verify the HMAC signature before processing. Reject unsigned or invalid requests.
  4. 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"

​
Retry policy

Failed deliveries (non-2xx response or timeout) are retried with exponential backoff. After all retries are exhausted, the delivery is marked as failed in the delivery log.

Webhook Event Catalog

See every event type with exact payloads and handler examples.

CLI Webhook Forwarding

Forward webhooks to localhost during development.