Receivers

Webhook receivers, whose secret it is, the map, the filter and payment time.

A receiver is a URL of the form POST /hooks/<appId>/<name>. Receivers are standards, not providers: any sender that follows one of these schemes can call it. Pick the scheme from the sender's own webhook docs. verify names it:

Whose secret it is. Each relay holds one value the sender’s signatures are checked with, and on every scheme you choose whose it is, on the relay’s page in Webhooks:

• New secret for the sender to sign with. Gemmein makes it and shows it once (on svix, a Standard Webhooks whsec_…); give it to the sender in its webhook settings. Use it when the sender lets you set the secret. It is not offered for Stripe’s format, whose sender always makes its own. The signature and shared_token schemes start with one.
• Paste the sender’s signing secret. When the sender shows its own (Stripe and Standard Webhooks senders always do; their relays start waiting for it). At least 24 plain ASCII characters (22 when it mixes upper- and lower-case letters and digits), long, and not one pattern repeated. Stripe’s starts whsec_; a Standard Webhooks secret is whsec_ and base64. It is stored and never shown again.
• Paste the sender’s public key. On an ed25519 or ecdsa-p256-sha256 recipe (Discord, SendGrid). The sender signs with its private key and shows the public one: paste it as shown, in hex, base64 or a PEM block. Gemmein never makes this key, so the relay starts waiting for it; asking for one answers 400 provider_secret_required.

Your AI stores a sender’s value in Development by piping it: printf '%s' "$SECRET" | npx gemmein relays secret <name>. It is read from stdin only, never typed on the command line, printed or logged. In Live, your human pastes it on the relay’s page, after the code Gemmein emails. Storing a value replaces the current one at once and is a row in Logs; the value itself never is. A relay that calls your URL also has a signing secret of its own (see Calling your URL); a relay with no call_url has none.

The map. Up to twenty names, each a dotted path into the provider's body, such as events.0.details.customer_email. Three names have a special meaning:

• event_id is the dedupe key. A repeat answers duplicate: true and runs nothing. Without it, the body's hash deduplicates within the same UTC day.
• event_type is what when usually reads.
• One of three keys names the person (table below). A map that carries two of them is refused when the relay is saved: the id and the token could name different people, and the event would land on whichever was tried first.

Every other name is available in templates as {{mapped.name}}.

Only an address can create a person, because an address reaches someone who can be told they have an account. A value a third party chose that matches nothing names no one. A key that resolves to nobody is not a refusal: the event is recorded and answered 200, and the run result reads person_not_found with the key that was tried, never its value.

Payment time: paid_at

A person who deletes their account and buys again is a new customer; a payment from before the deletion grants nothing. Map the provider's payment-time field as paid_at on every relay that grants (access, credits, a product or a plan) so Gemmein can tell before from after. It takes unix seconds, milliseconds or an ISO date; a time later than the event's arrival counts as its arrival. Without paid_at, a payment for a deleted account's address invites no one and grants nothing. It shows on the Errors page for you to decide: refund it, or grant it by hand if it is a new purchase. The error never contains the address.

The filter. when filters the mapped fields. Per field, it takes a literal (an exact match) or an object of operators in the list's filter grammar (see Data). Its keys must be in the map. A non-match answers 200 with ignored: "when" and records no event.

The receiver answers 200 with { received: true, eventId } only once the event is stored. Storing the event is the acknowledgement, and nothing runs before it.

The URL names no environment. The secret decides which environment's relay receives, so Development and Live may share a name, each with its own secret.