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

Optional
  • 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}})
  )
}
Context Vars: 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}})
    }
  }
}
Context Vars: 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).