Webhooks

Ratio sends HTTP POST callbacks to your registered webhook URL when events occur. Use webhooks for real-time event-driven integration without polling.

Configuration

Setting	Details
URL	Your HTTPS endpoint, configured during onboarding
Secret	HMAC-SHA256 key used for signature verification
Timeout	5 seconds — return HTTP `200` to acknowledge receipt

Event types

Event	Trigger
`settlement.confirmed`	Swap settled on-chain successfully
`settlement.failed`	Swap execution failed (on-chain revert)
`quote.expired`	Firm quote expired without execution
`system.state_change`	A corridor’s system state changed

Payloads

settlement.confirmed

Sent when a swap is confirmed on-chain.

{
  "event": "settlement.confirmed",
  "timestamp": "2026-02-27T10:00:32Z",
  "data": {
    "execution_id": "EX-9910-USD-IDR",
    "quote_id": "QT-8821-USD-IDR",
    "pair": "USD-IDR",
    "status": "SETTLED",
    "filled_rate": 16020.00,
    "source_amount": 50000,
    "destination_amount": 801000000,
    "tx_hash": "0xKAIA...ABC",
    "settled_at": "2026-02-27T10:00:32Z"
  }
}

settlement.failed

Sent when a swap execution fails due to an on-chain revert.

{
  "event": "settlement.failed",
  "timestamp": "2026-02-27T10:00:33Z",
  "data": {
    "execution_id": "EX-9911-USD-IDR",
    "quote_id": "QT-8822-USD-IDR",
    "pair": "USD-IDR",
    "status": "FAILED",
    "reason": "ON_CHAIN_REVERT",
    "tx_hash": "0xKAIA...DEF"
  }
}

quote.expired

Sent when a firm quote reaches its expiry_timestamp without being executed.

{
  "event": "quote.expired",
  "timestamp": "2026-02-27T10:01:00Z",
  "data": {
    "quote_id": "QT-8823-USD-SGD",
    "pair": "USD-SGD",
    "expired_at": "2026-02-27T10:00:45Z"
  }
}

system.state_change

Sent when a corridor transitions between system states.

{
  "event": "system.state_change",
  "timestamp": "2026-02-27T10:05:00Z",
  "data": {
    "corridor": "MYR-IDR",
    "previous_state": "NORMAL",
    "new_state": "PROTECT",
    "reason": "VOLATILITY_ELEVATED"
  }
}

Signature verification

Every webhook request includes a signature header you must verify before processing the payload:

X-Ratio-Signature: sha256=<hex_digest>

Compute the HMAC-SHA256 of the raw request body using your webhook secret, then compare the result against the header value. Reject any request where the signature does not match.

import hmac, hashlib

def verify(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

const crypto = require('crypto');

function verify(body, signature, secret) {
  const expected = crypto.createHmac('sha256', secret).update(body).digest('hex');
  return signature === `sha256=${expected}`;
}

Retry policy

If your endpoint does not return HTTP 200 within 5 seconds, Ratio retries with exponential backoff:

Attempt	Delay
1st retry	10 seconds
2nd retry	30 seconds
3rd retry	2 minutes
4th retry	10 minutes
5th retry	1 hour

After 5 failed attempts the webhook is marked as failed. Query the execution status directly via the API as a fallback.

Best practices

Always verify the X-Ratio-Signature header before processing any payload. Discard requests that fail verification.

Make your handler idempotent. The same event may be delivered more than once. Use execution_id or quote_id to deduplicate.
Return 200 immediately, then process asynchronously. Your handler must respond within 5 seconds. Offload any slow processing to a queue or background task.
Log the full payload. Retain raw payloads for debugging and reconciliation.

Overview

Endpoints

Configuration

Event types

Payloads

settlement.confirmed

settlement.failed

quote.expired

system.state_change

Signature verification

Retry policy

Best practices

​Configuration

​Event types

​Payloads

​settlement.confirmed

​settlement.failed

​quote.expired

​system.state_change

​Signature verification

​Retry policy

​Best practices

Configuration

Event types

Payloads

settlement.confirmed

settlement.failed

quote.expired

system.state_change

Signature verification

Retry policy

Best practices