The signature recipe

Describe any sender's signature, worked examples, and unsigned events.

A receiver checks a webhook by its standard, not by who sends it: there is no list of allowed providers. Read the sender’s own webhook docs for four answers, and the relay’s verify block records them. Every field is optional except where the signature is; left out, it is the plain case: an HMAC-SHA256 of the raw body, hex, in one header.

The save checks the template: each placeholder appears once; a digit or {params} never comes right after {timestamp}; {timestamp} must be in the text when a timestamp source is named, and a source is named when {timestamp} or {token} is used; {body} and {params} stay out of the text when the signature itself is in the body. Anything else answers 400 invalid_definition, naming what to fix, and nothing is saved. A definition that saves but describes the signature differently from how the sender signs (the timestamp in another place, another separator, other signed text, or a receiver URL given to the sender with a ?query after it) answers 401 bad_signature on every event, and nothing runs.

Worked examples

Each recipe below is proven against the sender’s published spec by a test that runs on every Gemmein release. A sender is named here only while its test passes.

A form post (Twilio’s) is read as its fields, so a map names them directly: "event_id": "MessageSid". A sender that signs no timestamp (GitHub, Intercom, Square, Twilio) has no replay window: a resent event is recognised by its event_id, or without one by its body within the UTC day, and runs once. Events are kept 30 days after they finish, so a call to such a sender captured more than 30 days earlier could run once more. A signature header listing more than 8 signatures answers 400 too_many_signatures.

Names are trademarks of their respective owners and are used only to identify services whose signed webhooks Gemmein can verify. Gemmein is not affiliated with, endorsed by or sponsored by any of them.

Unsigned events

Two kinds of receiver don’t sign the event itself: a {token} recipe (Mailgun), where the signature covers a timestamp and a token but not the event, so anyone who captures one signed call can send it with any content, once, within 5 minutes; and shared_token, where the same token comes on every call, so anyone who has it can send any number of events at any time. Gemmein accepts each signature of a {token} or {params} recipe once, still for 24 hours after the relay is deleted.

By default such a relay only writes records and calls your URL. Every other action (grant_access, grant_credits, grant_plan, fulfil_product, start_run, revoke_access, revoke_plan, refund_product, email_person) is refused when the relay is saved, with 400 invalid_definition, and so is a map naming person_email, which creates people. The same refusal holds in gemmein dev, gemmein sync, the dashboard and Promote.

The safer way to act on such a sender: call_url to your function, which checks the event with the sender’s own API and writes a record with your secret key; a data_change relay on that collection then acts. A record a relay writes never fires a data_change relay, so write_record can’t be turned into a grant.

To let the relay act anyway, set the opt-in on its trigger: "trigger": { "kind": "receiver", …, "trustUnsignedEvents": true }. Your AI asks you before setting it. The relay’s page shows the warning beside it, Logs records who turned it on, and Promote carries it to Live with the warning in its preview. The Go live page lists each such relay with its warning. A save that widens what a captured call buys (a longer toleranceSeconds, no timestamp, or a move to shared_token) shows the warning again. The opt-in is refused on a sender that signs the event. The RevenueCat and shared-token templates on the Webhooks page carry it, with the warning in their note.