Webhooks

Receiving webhooks

How Limenia calls your webhook — headers, signature check with test vector, retries, ordering, applying actions and showing the statement of reasons.

Limenia tells your backend about decisions with webhooks. Set the URL in the dashboard (tab Connection → Webhook, see Quickstart). The events and their payloads are on Webhook events.

Request

Limenia sends a POST with a JSON body to your webhook URL:

Header Content
Content-Type application/json
User-Agent Limenia-Webhooks/1
Limenia-Event-Id evt_ plus a ULID, equal to id in the body
Limenia-Event-Type decision.created, subject.status_changed, appeal.resolved, reports.resolved, review.decided or test.ping
Limenia-Signature t=<unix seconds>,v1=<hex>

Limenia sends from no fixed address, so an IP allowlist is not possible. Rely on the signature.

Verifying the signature

  1. Split Limenia-Signature at commas. t must appear exactly once, v1 at least once. Ignore unknown keys.
  2. Reject the request if t is more than 300 seconds away from your clock, in either direction. Keep the server clock in sync (NTP).
  3. Compute hex(HMAC-SHA256(secret, t + "." + rawBody)) over the raw body exactly as received. Do not parse and re-serialize it first.
  4. The signature is valid if any v1 value matches, for the current secret or (while rotating) the previous one. Compare in constant time.
  5. On failure answer 401 and do nothing else.

The signing secret is the whole string as shown in the dashboard, including the prefix whsec_ (49 characters). Use it as the HMAC key byte for byte; do not decode it.

Test vector

Test your code against it before going live:

Secret whsec_test
t 1800000000
Body {"id":"evt_1"}
v1 45705be2a45ab5acdd1395cc695e9e7073125385ec24194921c401dff44176f8
Shell
printf '%s' '1800000000.{"id":"evt_1"}' | openssl dgst -sha256 -hmac whsec_test
# → 45705be2a45ab5acdd1395cc695e9e7073125385ec24194921c401dff44176f8

(t=1800000000 is far from now, so a correct receiver rejects this header with timestamp_out_of_range; use the vector in unit tests with an injected clock.)

Limenia signs every delivery attempt anew with a new t; the body stays the same across retries.

Rotating the secret

Limenia signs only with the current secret and currently sends exactly one v1. After Rotate secret, deliveries fail until your receiver knows the new secret, but they are retried (first retry after 1 minute, for about 20 hours). Easiest: accept a list of secrets (LIMENIA_WEBHOOK_SECRET and LIMENIA_WEBHOOK_SECRET_PREVIOUS), add the new one, deploy, remove the old one later.

Answers, retries, order

  • Answer 2xx (e.g. 204) within 10 seconds (including connection setup). Do heavy work asynchronously, but acknowledge only after the event is safely stored.
  • Every other answer, a timeout or a connection error is a failure, also 4xx and 3xx (redirects are not followed). Limenia retries up to 12 attempts, backoff from 1 minute doubling up to 6 hours, about 20 hours in total. Afterwards the delivery is failed in the Delivery log; an admin can resend it.
  • Pause after repeated failures: after 5 timeouts, connection errors, 429 or 5xx answers in a row, Limenia pauses the webhook deliveries of the app for 5 minutes. Paused deliveries are not lost: they keep their retry schedule and their last attempt always runs. After the pause one delivery goes through; when it succeeds the others follow. A successful Test webhook ends the pause at once. Firebase, Supabase and RevenueCat actions are not held up by a slow webhook.
  • Answer with an error only when you want a retry. Acknowledge duplicates, unknown event types and events you ignore with 2xx. An action your app does not support: acknowledge with 2xx and log it (IDs only).
  • At least once: the same event can arrive several times with the same id and body but a new signature. Deduplicate by id (= Limenia-Event-Id), mark it processed only after handling it, and make actions idempotent (set a state, do not toggle it).
  • Order not guaranteed: remember per user and per content the time of the last applied change and skip older events: decision.decidedAt, or createdAt for subject.status_changed. Skip only strictly older events, not equal ones. So a late suspend_user never overrides a later restore.

Delivery log

Every delivery attempt appears in the dashboard under Delivery log with its status (pending, delivered, failed) and, on failure, an error code:

Error code Meaning Retried?
http_status Your receiver answered with something other than 2xx (also 3xx and 4xx) yes
timeout No answer within 10 seconds yes
connection_failed DNS, TLS or the connection failed yes
blocked_url The URL or the address it resolves to is not public https no

Limenia reads at most 64 KiB of your answer and ignores its content. A delivery that is failed after all attempts can be resent by an admin from the delivery log; it then gets a new series of attempts.

Applying actions

Every decision has exactly one action; removing content and suspending its author are two decisions. Act on action, not on whether content or subject is present.

action Status in Limenia What your app does
dismiss unchanged Nothing. Inform reporters via reports.resolved.
remove_content unchanged Remove or permanently hide content.externalContentId
restrict_content unchanged Restrict visibility (e.g. out of feeds and search). After a restricted review: publish restricted.
warn_user warned (if active or the suspension has already ended) Warn the user; do not restrict the account
suspend_user suspended until suspendUntil Block the account until suspendUntil (UTC). Lift it yourself at that time; subject.status_changed can come up to an hour later.
ban_user banned Block the account permanently
restore account: active; content: unchanged restoreScope: "account": unblock the account. restoreScope: "content": restore the content (with reviewId: publish the submitted content as submitted); do not touch the account.
reject_submission unchanged Reviews only: do not publish content.externalContentId

Decisions with reviewId never change the account.

Showing the statement of reasons

  • Show statementOfReasons.text to the affected user for every decision except dismiss (for restore it is a notice of the lifting). If the account is blocked, use a channel outside the app (e-mail, login screen).
  • The text is ready-made, with \n line breaks, in the tenant’s language. Render it as plain text, never HTML or Markdown: it contains the moderator’s free text.
  • For your own layout or other languages use structured. Show the automation note when automation is partial or full.
  • decision.created never names reporters.

Under the DSA you must show the statement of reasons to the affected user (Art. 17 DSA, see DSA).