2026-06-17 02:09:36 +03:00
..
2026-06-17 02:09:36 +03:00
2026-06-17 02:09:36 +03:00
2026-06-17 02:09:36 +03:00
2026-06-17 02:09:36 +03:00
2026-06-17 02:09:36 +03:00

webhook-relay

A small Rust microservice that receives SettleKit webhook events and fans them out to any number of subscriber URLs. Each outbound delivery is HMAC-signed with the canonical SettleKit t=<ts>,v1=<hex> scheme, retried with exponential backoff, and recorded in an in-memory delivery log.

Built with axum 0.7, tokio, and reqwest (rustls). The POST /events handler returns immediately — actual HTTP delivery runs on spawned tokio tasks.

Architecture

Module Responsibility
config.rs Env-driven configuration with fail-fast validation.
signer.rs HMAC-SHA256 signing producing t=<ts>,v1=<hex> over "<t>.<raw body>".
subscribers.rs Concurrent DashMap registry of subscriber endpoints + filtering.
relay.rs Fan-out engine: select subscribers, POST with backoff, delivery log.
routes.rs Axum handlers and router.
error.rs RelayError rendered as the SettleKit {"error":{code,message}} envelope.
main.rs Wiring + graceful shutdown.

Configuration

All configuration comes from the environment and is validated at startup.

Variable Required Default Description
SIGNING_SECRET yes — HMAC key applied to every outbound body (min 8 chars).
PORT no 8091 TCP port the HTTP server binds to.
MAX_RETRIES no 5 Maximum delivery attempts per subscriber (> 0).
RETRY_BASE_MS no 500 Backoff base in ms (> 0). Delay = base * 2^attempt.
RUST_LOG no info Tracing filter, e.g. webhook_relay=debug.

Running

# from services/webhook-relay/
SIGNING_SECRET="whsec_super_secret_value" \
PORT=8091 \
MAX_RETRIES=5 \
RETRY_BASE_MS=500 \
cargo run --release
# tests
cargo test

Endpoints

All success responses use the SettleKit envelope {"data": ...}; errors return a non-2xx status with {"error":{"code","message"}}.

Method Path Description
GET /healthz Liveness probe.
POST /subscribers Register a subscriber. Returns 201 + the record.
GET /subscribers List all subscribers.
DELETE /subscribers/:id Remove a subscriber. 404 if unknown.
POST /events Accept an event, fan out, return 202 + delivery ids.
GET /deliveries Recent delivery log (?limit= 1..1000, default 100).

Subscriber shape

{
  "id": "b1f1...",
  "url": "https://example.com/hook",
  "event_types": ["payment.created", "refund.created"],
  "active": true
}

event_types is a filter — an empty list matches all events. On register, event_types defaults to [] and active defaults to true.

Event shape (POST /events)

Matches the SettleKit webhook payload {id?, type, data, createdAt?}. id and createdAt are synthesized when omitted; the exact serialized JSON is what gets signed and delivered.

{
  "type": "payment.created",
  "data": { "id": "pay_123", "amount": { "amount": "25.00", "currency": "USDC" } }
}

Delivery record (GET /deliveries)

{
  "id": "9c2e...",
  "subscriber_id": "b1f1...",
  "url": "https://example.com/hook",
  "event_type": "payment.created",
  "status": "delivered",          // pending | delivered | failed
  "attempts": 1,
  "last_status": 200,
  "last_error": null
}

Signing scheme

Every delivery carries:

SettleKit-Signature: t=<unix-seconds>,v1=<hex>
SettleKit-Event: <event.type>
Content-Type: application/json

where <hex> is the lower-case hex HMAC-SHA256(SIGNING_SECRET, "<t>.<raw_json_body>"). This is the canonical (Stripe-style) SettleKit webhook scheme — identical to what the API itself signs — so the constant-time verify_signature helpers shipped in every SettleKit SDK (TypeScript, Python, Go, Rust) accept relay deliveries without special-casing. Subscribers verify by recomputing the HMAC over "<t>.<exact received body>" and comparing in constant time, optionally rejecting a stale t for replay protection.

Verify with any SDK (no re-implementation needed), e.g. TypeScript:

import { verifyWebhookSignature } from "@settlekit/sdk";

const ok = verifyWebhookSignature(secret, rawBody, req.header("SettleKit-Signature"));

…or by hand in Node:

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((s) => s.trim().split("=")));
  const expected = createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(parts.v1 ?? "");
  return a.length === b.length && timingSafeEqual(a, b);
}

Retry / backoff

Each delivery is attempted up to MAX_RETRIES times. The first attempt fires immediately; before attempt n (1-indexed from 0) the task sleeps RETRY_BASE_MS * 2^n milliseconds. With defaults (base=500, retries=5):

attempt 0: 0ms
attempt 1: 1000ms
attempt 2: 2000ms
attempt 3: 4000ms
attempt 4: 8000ms

A 2xx response marks the delivery delivered and stops retrying. Exhausting all attempts marks it failed. last_status: 0 indicates a transport-level failure (connection refused, timeout, DNS), with details in last_error.

Example: end-to-end with curl

# 1. Register a subscriber (receives all events).
curl -s -X POST http://localhost:8091/subscribers \
  -H 'content-type: application/json' \
  -d '{"url":"https://webhook.site/your-uuid","event_types":["payment.created"]}'
# -> 201 {"data":{"id":"<sub-id>","url":"...","event_types":["payment.created"],"active":true}}

# 2. List subscribers.
curl -s http://localhost:8091/subscribers

# 3. Emit an event — fans out to matching subscribers.
curl -s -X POST http://localhost:8091/events \
  -H 'content-type: application/json' \
  -d '{
        "type":"payment.created",
        "data":{"id":"pay_123","amount":{"amount":"25.00","currency":"USDC"}}
      }'
# -> 202 {"data":{"eventId":"evt_...","type":"payment.created","deliveryIds":["<id>"],"subscriberCount":1}}

# 4. Inspect the delivery log.
curl -s 'http://localhost:8091/deliveries?limit=20'

# 5. Remove the subscriber.
curl -s -X DELETE http://localhost:8091/subscribers/<sub-id>

Relationship to SettleKit

This relay is a self-contained fan-out layer. It mirrors the SettleKit webhook signing scheme (SettleKit-Signature: t=<ts>,v1=<hmac sha256 of "<t>.<raw body>">) and event payload shape ({id, type, data, createdAt}) so that subscribers written against SettleKit's first-party webhooks — including the SDK verify_signature helpers — can consume relayed events unchanged.