Verify Modern Treasury webhooks. Modern Treasury sends X-Signature,
the hex HMAC-SHA256 of the raw request body keyed with your webhook
key (Developers → Webhooks). Nothing else is signed: X-Event-Time
and the other headers are not covered, so there is no signed
timestamp to enforce a replay window with. Deduplicate on
X-Webhook-ID (stable across retries) and act on the current state
of the object (re-fetch it) rather than on the payload alone.
Other headers: X-Topic (e.g. "payment_order"), X-Event-ID,
X-Event-Time, X-Delivery-ID (changes per attempt), X-Live-Mode
("true" or "false"). The body is {event, data}: event names
what happened (e.g. "completed"), data is the object. Modern
Treasury waits five seconds for a 2xx and retries with backoff (15
attempts over about a day and a half), then pauses the endpoint.
Context Vars
modern-treasury.webhook.key
Functions
construct-event
fn (request: Map): Any
fn (request: Map, key: Str): Any
Verify a request (see verify-request) and return its Event, or an
Err when the signature doesn't verify. The 2-arity form takes an
explicit key.
Example
handle (request) {
e ::modern-treasury::webhooks/construct-event(request)
if(is-err(e),
::hot::http/HttpResponse({status: 401, body: "invalid signature"}),
::hot::http/HttpResponse({status: 200, body: {received: e.webhook_id}})
)
}
modern-treasury.webhook.key
parse-event
fn (request: Map): Event
Parse a webhook request (verify it first) into an Event. The body is
read from the raw body, so it works whether or not Hot already decoded
it. Errs when the body isn't a JSON object.
Example
request {
headers: {X-Topic: "payment_order", X-Webhook-ID: "wh_1", X-Live-Mode: "false"},
body: {event: "completed", data: {id: "po_1", status: "completed"}}
}
e ::modern-treasury::webhooks/parse-event(request)
e.topic // "payment_order"
e.event // "completed"
e.id // "po_1"
e.webhook_id // "wh_1"
e.live_mode // false
sign
fn (key: Str, body: Str | Bytes): Str
The X-Signature value Modern Treasury would send for body: lowercase
hex HMAC-SHA256 under key. Use it to build test deliveries.
Example
key ::hot::ctx/get("modern-treasury.webhook.key")
signature ::modern-treasury::webhooks/sign(key, "{\"event\":\"completed\"}")
verify-request
fn (request: Map): Bool
fn (request: Map, key: Str): Bool
True when an inbound request carries a valid X-Signature over its
raw body. The 1-arity form reads modern-treasury.webhook.key and
fails the run when it is unset; an explicit empty key never verifies.
Example
mt-webhook
meta {webhook: {service: "modern-treasury", path: "/modern-treasury/webhook"}}
fn (request) {
cond {
not(::modern-treasury::webhooks/verify-request(request)) => {
::hot::http/HttpResponse({status: 401, body: "invalid signature"})
}
=> {
e ::modern-treasury::webhooks/parse-event(request)
// enqueue e.webhook_id, e.topic, e.event, e.id for processing
::hot::http/HttpResponse({status: 200, body: {received: true}})
}
}
}
modern-treasury.webhook.key
verify-signature
fn (body: Str | Bytes, signature: Str, key: Str): Bool
True when signature (hex) is the HMAC-SHA256 of body under key,
compared in constant time. An empty key or signature never verifies.
Pass the raw body, never a re-serialized one.
Example
key ::hot::ctx/get("modern-treasury.webhook.key")
body "{\"event\":\"completed\"}"
signature ::modern-treasury::webhooks/sign(key, body)
::modern-treasury::webhooks/verify-signature(body, signature, key)
Types
Event
Event type {
topic: Str?,
event: Str?,
data: Any?,
id: Str?,
webhook_id: Str?,
event_id: Str?,
event_time: Str?,
live_mode: Bool?
}
A parsed Modern Treasury webhook: topic (X-Topic, e.g. "payment_order"), event (e.g. "completed"), data (the object), id (data.id), webhook_id (X-Webhook-ID, the dedupe key), event_id, event_time, live_mode (Bool, from X-Live-Mode).