Webhooks

A webhook turns HTTP requests from another app (a CI, a monitor, a shop) into events of one source, without a publish key and without code. A mapping, a JSON object stored on the source, reads each request and names the event fields. GitHub, Coolify, Stripe, HOSTKEY and remote uptime checkers use the same receiver with seeded mappings.

New source: send a test, review, activate

A new webhook starts pending: Citadel keeps its deliveries and publishes no event until the webhook is activated. Readers and Pager see nothing from a pending webhook.

1. In the admin panel, open Events, select the source, and turn on Webhook. The admin panel shows the URL with its token once.
2. Paste the URL into the sending app and send one test delivery from the app. Citadel keeps the delivery and answers held: pending review.
3. Write the mapping in the admin panel and run Preview over the kept deliveries. Save.
4. Optional: set a signature and mark it required; set the allowed URL hosts.
5. Activate. With Publish the kept deliveries, the held deliveries run through the saved mapping, oldest first, under the noise budget and the duplicate rules. Without it, each held delivery's outcome becomes dropped: not published at activation.

Built-in webhooks start active. Turning a webhook off makes the webhook disabled; turning the webhook on again restores pending or active. The admin panel shows each source's held deliveries.

The receiver

POST /v1/events/hooks/in/{token}

The token is 32 random bytes, base64url (43 characters). Citadel stores the token's SHA-256 only; the admin panel shows the URL once, then the last 4 characters. Rotate issues a new token and invalidates the old one at once.

Every delivery takes the same steps:

1. Find the webhook by token. Refuse unknown tokens, turned-off webhooks and archived sources.
2. Check the signature when one is set (see Signatures).
3. Pending webhook: keep the delivery, answer held: pending review, stop.
4. Parse the body.
5. Run the source's mapping: zero or more events.
6. Drop the delivery when the delivery repeats one (see Duplicates).
7. Publish each event: field validation, URL host filter, idempotency_key dedupe, noise budget, rate limit.
8. Keep the delivery with its outcome.

{"ok":true,"outcome":"2 events: evt_01JBX7Q2W8V5K3M9N4P6R2T8YC,dropped: rule 1,evt_01JBX7Q2W8V5K3M9N4P6R2T8YD","events":["evt_01JBX7Q2W8V5K3M9N4P6R2T8YC","evt_01JBX7Q2W8V5K3M9N4P6R2T8YD"]}

Citadel keeps the newest 200 deliveries per source with their outcome, bodies cut at 256 KiB, for Preview and Replay.

Request parsing

$headers leaves out Authorization, Proxy-Authorization, Cookie, the signature header and forwarding headers (CF-Connecting-IP, X-Forwarded-For, X-Real-IP, True-Client-IP).

Duplicates

A sender may deliver one request twice: a retry after a timeout, or a manual resend. Citadel dedupes each delivery on the first key available:

The body key applies only to a delivery with an event that has neither idempotency nor a delivery header. The 10 minutes count from the original delivery, not from its duplicates: a body resent every 5 minutes makes one event every 10 minutes, and a monitor's identical down body on the next day makes a new event. "dedupe_body": false in the mapping turns the body key off; the seeded uptime mapping sets false, because a remote checker sends the same report every minute.

Mapping reference

Every key is optional. No mapping, or {}, makes one event per delivery: type webhook, severity info, text a summary of the body.

Keys

A value is a template string or a composite value. Severity names: debug, info, notice, warn, error, critical. Aliases, case-insensitive: warning, err, fatal, information.

Paths

A key that contains . is not reachable.

Templates

{{path}} writes the value at path: strings as they are, numbers and booleans plain, objects and arrays as compact JSON. {{path|fallback}} writes fallback when the value is missing, null or "". {{path|filter|filter:arg}} runs filters left to right; a segment that is not a filter name starts the fallback. A template without {{ is a constant.

money writes whole amounts without decimals (€29) and zero-decimal currencies (jpy, krw, and 14 more) in whole units.

Composite values

Inside each, paths read the element; $root reads the body.

Conditions

{"path": p, <operator>: value}, or a combination:

eq, ne, contains, gt and lt also compare with another value: {"path": "ref", "ne": {"template": "refs/heads/{{repository.default_branch}}"}} or {"path": "paid", "lt": {"path": "total"}}. A missing value on either side compares as "".

Drop rules and cases

drop runs first: an item that matches any rule makes no event, with outcome dropped: rule N or dropped: <reason> for {"when": condition, "reason": template}.

cases run next, in order. The first case whose when holds (a case without when always holds) applies:

• A case with drop drops the item; the outcome is dropped: <drop>, or dropped: case N when drop renders empty.
• Any other case overrides the mapping's fields with its own: type, text, detail, subject, url, severity, sticky, lifetime, idempotency, occurred_at. Case data keys replace or add to the mapping's data keys.

Fields outside every case apply to every item.

data

A value over 300 bytes becomes a string cut to 300 characters.

Enrichers

An enricher adds data that the request does not carry. A mapping opts in with "enrich": ["<name>"].

Preview and Replay run enrichers without changing uptime state.

Validation and limits

Saving a mapping with an unknown key, a bad path, template, filter, regular expression, severity name or condition fails with 400 invalid_field; meta.field names the location, for example mapping.cases[2].severity.rules[0].when.

A mapping that fails at run time (a split path that is missing or not an array) makes the fallback event, and the outcome carries the error. Citadel never loses a delivery to its mapping.

Examples

A CI webhook with severity rules

{
  "repository": {"name": "narkis"},
  "build": {"id": 4812, "number": 312, "status": "failed", "branch": "main", "duration_s": 340,
            "message": "go test ./... failed: TestCheckout", "url": "https://ci.example.com/narkis/312",
            "commit": "a1b2c3d", "finished_at": "2026-10-15T10:02:03Z"}
}

{
  "drop": [{"path": "build.branch", "matches": "^dependabot/"}],
  "type": "ci.{{build.status}}",
  "text": "**{{repository.name}}** build #{{build.number}} {{build.status}}",
  "detail": "{{build.message}}",
  "subject": "{{repository.name}} · {{build.branch}}",
  "url": "{{build.url}}",
  "severity": {"rules": [
      {"when": {"path": "build.status", "in": ["failed", "errored"]}, "then": "error"},
      {"when": {"path": "build.duration_s", "gt": 900}, "then": "warning"}],
    "default": "info"},
  "sticky": {"path": "build.status", "eq": "failed"},
  "idempotency": "ci-{{build.id}}",
  "occurred_at": "{{build.finished_at}}",
  "data": {"commit": "build.commit"}
}

[
  {"type": "ci.failed", "severity": "error", "text": "**narkis** build #312 failed",
   "detail": "go test ./... failed: TestCheckout", "subject": "narkis · main",
   "url": "https://ci.example.com/narkis/312", "sticky": true, "idempotency_key": "ci-4812",
   "occurred_at": "2026-10-15T10:02:03Z", "data": {"commit": "a1b2c3d"}}
]

A batch with split

{"monitor": "homelab", "sent_at": 1792058523, "alerts": [
  {"id": "a-91", "check": "disk /data", "state": "WARNING", "value": "87%", "host": "web-2"},
  {"id": "a-92", "check": "backup", "state": "OK", "host": "web-2", "test": true},
  {"id": "a-93", "check": "postgres", "state": "CRITICAL", "host": "db-1"}
]}

One event per alert, test alerts dropped, the severity read from the alert's state (WARNING is an alias of warn; OK is no severity name, so info):

{
  "split": "alerts",
  "drop": [{"when": {"path": "test", "eq": true}, "reason": "test alert {{id}}"}],
  "type": "{{$root.monitor}}.{{check}}",
  "text": "{{host}}: {{check}} {{state}} {{value}}",
  "subject": "{{host}}",
  "severity": "{{state}}",
  "sticky": {"path": "state", "eq": "critical"},
  "idempotency": "{{id}}",
  "occurred_at": "{{$root.sent_at}}"
}

[
  {"type": "homelab.disk.data", "severity": "warn", "text": "web-2: disk /data WARNING 87%", "subject": "web-2",
   "sticky": false, "idempotency_key": "a-91", "occurred_at": "2026-10-15T10:02:03Z"},
  {"dropped": "test alert a-92"},
  {"type": "homelab.postgres", "severity": "critical", "text": "db-1: postgres CRITICAL", "subject": "db-1",
   "sticky": true, "idempotency_key": "a-93", "occurred_at": "2026-10-15T10:02:03Z"}
]

The outcome reads 2 events: evt_…,dropped: test alert a-92,evt_….

GitHub pushes (from the seeded mapping)

An excerpt of the github source's default mapping: the push events. The full default mapping also covers pull requests, failed workflow runs and releases.

{"x-github-event": "push", "x-github-delivery": "6f1e7a20-b5d1-11ef-8f2a-1c3e2d9a7b01"}

{
  "ref": "refs/heads/main",
  "compare": "https://github.com/albastar/site/compare/1a2b3c4d5e6f...9f3c2e1aa0b1",
  "repository": {"name": "site", "default_branch": "main"},
  "pusher": {"name": "Adam"},
  "sender": {"login": "adam", "type": "User"},
  "commits": [
    {"id": "1a2b3c4d5e6f", "message": "Fix login redirect\n\nThe session cookie was not sent.", "timestamp": "2026-10-31T09:58:00Z"},
    {"id": "9f3c2e1aa0b1", "message": "Add invoice export", "timestamp": "2026-10-31T10:01:00Z"}
  ]
}

{
  "kind": "{{$headers.x-github-event}}",
  "delivery": "{{$headers.x-github-delivery}}",
  "drop": [{"when": {"path": "$headers.x-github-event", "eq": "ping"}, "reason": "ping"}],
  "severity": "info",
  "subject": "{{repository.name}}",
  "idempotency": "{{$headers.x-github-delivery|prefix:github:}}",
  "cases": [
    {"when": {"all": [{"path": "$headers.x-github-event", "eq": "push"},
                      {"path": "ref", "ne": {"template": "refs/heads/{{repository.default_branch}}"}}]},
     "drop": "not the default branch"},
    {"when": {"path": "$headers.x-github-event", "eq": "push"},
     "type": "github.push",
     "url": "{{compare}}",
     "text": {"join": "", "parts": [
       "{{repository.name}}: {{commits|count}} ",
       {"if": {"path": "commits.1", "exists": true}, "then": "commits", "else": "commit"},
       " by {{pusher.name|or:sender.login}} — {{commits.0.message|firstline}}"]},
     "detail": {"each": "commits", "value": "{{id|short}} {{message|firstline}}", "join": "\n"},
     "occurred_at": "{{commits.-1.timestamp}}"},
    {"drop": "event {{$headers.x-github-event}} not mapped"}
  ]
}

[
  {"type": "github.push", "severity": "info", "text": "site: 2 commits by Adam — Fix login redirect",
   "detail": "1a2b3c4 Fix login redirect\n9f3c2e1 Add invoice export", "subject": "site",
   "url": "https://github.com/albastar/site/compare/1a2b3c4d5e6f...9f3c2e1aa0b1", "sticky": false,
   "idempotency_key": "github:6f1e7a20-b5d1-11ef-8f2a-1c3e2d9a7b01", "occurred_at": "2026-10-31T10:01:00Z"}
]

idempotency uses GitHub's X-GitHub-Delivery, so a redelivery of the same delivery returns the stored event.

Preview and replay

• Preview runs an unsaved mapping over the source's kept deliveries, newest first (20 by default, at most 50), and shows per delivery the events, dropped items and errors. Preview stores and publishes nothing.
• Replay runs the saved mapping over one kept delivery and publishes the events, outside the noise budget. idempotency keys, delivery headers and the body key still dedupe. A delivery whose kept body was cut at 256 KiB cannot be replayed. A pending webhook refuses Replay: activate the webhook first.
• Activate ends a pending webhook's review and publishes the held deliveries or marks them not published; see New source.
• Reset to default replaces a built-in webhook's mapping with the mapping shipped in Citadel.

Signatures

A signature proves that a delivery came from the app: the app signs each request body with a secret shared with Citadel, and Citadel recomputes the signature.

With required: false, a delivery without the signature header is accepted on its token; a delivery with the header is still checked. Citadel encrypts the secret (AES-GCM) and never shows the secret again. Saving a signature without secret keeps the stored secret.

Security

• A 404 costs one SHA-256 and one lookup, the same for every token.
• Every 404 and 401 from a client address counts against one allowance per address across all webhook URLs: 30 refusals, refilling 1 every 2 seconds. Accepted deliveries never count. The client address is Cloudflare's CF-Connecting-IP: the per-address limit relies on every request arriving through Cloudflare.
• The admin panel shows per source: refused requests in the last 24 hours and the last 20 refusals.
• Replays: Stripe signatures older than 5 minutes are refused. Repeated deliveries dedupe on idempotency, a delivery header or the body; see Duplicates.
• New webhooks: a webhook starts pending and publishes nothing until the admin activates the webhook, so a URL handed to a new app reaches no reader before review.
• Links: with allowed URL hosts set (exact hosts or *.domain, at most 20), a mapped url on another host is removed and the outcome says url dropped: host <host> not allowed. A url must be https://.
• Noise budget: at most 5 events of a source a minute reach readers one by one; the rest become one summary event.
• Rotate the token after a leak; the old URL returns 404 at once.

Built-in webhooks

Each built-in source has one webhook, seeded at startup with the default mapping. The URLs below predate the /hooks/in/{token} form and stay in service; each enters the same receiver. A built-in webhook can be turned off, edited and reset to its default mapping, not removed. Built-in webhooks start active.

GitHub and Stripe URLs carry no token: the signature is the only credential, and both URLs return 404 until the signing secret is set. A built-in source also accepts its token at POST /v1/events/hooks/in/{token}.

Errors