ankusa.sdk.webhook — io.github.jamescarr/ankusa-clj 0.1.0

The headers every receiver of Ankusa's HTTP sink needs, parsed off a request.

The HTTP sink sends these headers; the hook id is the only one that is always there:

Header	Key	Default
x-ankusa-id	:id	required: its absence means the request is not a delivery
x-ankusa-source	:source	""
x-ankusa-tenant	:tenant	nil
content-type	:content-type	nil
x-ankusa-dedupe-key	:dedupe-key	nil (also when empty)
x-ankusa-replay-id	:replay-id	nil (also when empty)
x-ankusa-idempotency-key	:idempotency-key	nil (also when empty)
x-ankusa-received-at	:received-at	nil (absent, empty, or not 1 to 15 decimal digits); unix milliseconds the edge accepted the hook
x-ankusa-body-sha256	:body-sha256	nil (absent, or not exactly 64 lowercase hex characters); the SHA-256 of the body sent
x-ankusa-verification / x-ankusa-verification-flagged	:verification	nil (also when the status header is empty)

The result also carries every request header under :headers, lowercased, so a receiver can read the provider's own headers the sink forwarded.

parse-headers clj

(parse-headers headers)

Parse the Ankusa headers out of headers: a map (Ring's :headers) or a seq of [name value] pairs. Names are strings or keywords and are matched case-insensitively; values may be strings, numbers, booleans, or keywords.

Returns {:id :source :tenant :content-type :dedupe-key :replay-id :idempotency-key :received-at :body-sha256 :verification :headers}, or throws :ankusa.sdk/MissingHookIdError when x-ankusa-id is absent or empty.

receive-delivery clj

(receive-delivery headers
                  body
                  {:keys [secrets allow-unsigned tolerance-seconds now]})

Judge one HTTP-sink delivery: is it signed, and what is its identity.

Ankusa's HTTP sink signs every delivery unless it is configured allow_unsigned: true, so a receiver is closed by default: without the sink's :secrets (or an explicit :allow-unsigned true) it refuses every delivery, because any host that can reach the receiver's URL could otherwise inject hooks.

headers as for parse-headers; body the raw bytes received. Options: :secrets (a secret or a seq of them; with any, the delivery MUST verify as in ankusa.sdk.signature/verify, and :allow-unsigned does not weaken that), :allow-unsigned (accept a delivery when no secret is configured, unverified), :tolerance-seconds and :now (as for verify).

Returns what parse-headers returns (including :verification) plus :verified (false only for an unsigned delivery :allow-unsigned let through). Throws :ankusa.sdk/InvalidSignatureError (answer 401) when there is no valid signature, "invalid_secret" when no secret is configured and :allow-unsigned is not set, and :ankusa.sdk/MissingHookIdError (400) when x-ankusa-id is absent. The signature is judged first.