Webhooks (contract between workers)

The global rules from the earlier interface docs apply:

• No JS and no inline styles; no unwrap in non-test code.
• Tests use tempfile::TempDir.
• Never put cargo target dirs or big files in /tmp.
• Every new crate is added at its latest version with cargo add and recorded in the root [workspace.dependencies].

Model

• A repo webhook has:
  • a URL (https, or http only when the config allows it);
  • a secret, encrypted at rest with the instance key the same way TOTP secrets are;
  • a content type (always application/json);
  • an event list: push, pull_request, issues, issue_comment, pull_request_review, create, delete, ping;
  • an active flag.
• Managing hooks needs Admin on the repo.
• Deliveries are rows in the DB:
  • the request: headers and body. The headers are queued without X-Forge-Delivery or the signature; after each attempt the stored headers are replaced with the ones actually sent;
  • the response: status, the first 64 KiB of the body, and timing;
  • attempt, a state (pending | ok | failed | gave_up), next_attempt_at, and a GUID.
• Retries use backoff 1m, 5m, 30m, 2h, 6h, then gave_up. "Redeliver" in the UI creates a new delivery with the same payload.
• Headers:
  • X-Forge-Event: <event>, X-Forge-Delivery: <guid>;
  • X-Forge-Signature-256: sha256=<hex HMAC-SHA256(secret, raw body)>;
  • User-Agent: forge-hookshot/<version>.
• Payloads are our own JSON. We deliberately don't copy the GitHub or Gitea schemas, but a similar shape is fine:
  • repository {id, owner, name, full_name, private, html_url, clone_url}, sender {id, username};
  • push: ref, before, after, commits[{id, message, author{name,email}, timestamp, url}] (max 20), total_commits, compare_url;
  • pull_request: action (opened|closed|reopened|merged|synchronize|edited|labeled|unlabeled|assigned|unassigned|milestoned|demilestoned), number, pull_request {title, body, state, merged, base, head, html_url}; the label, assignee and milestone actions add label {name, color}, assignee {username} or milestone {title} at the top level, as the issues event does;
  • issues: action (opened|closed|reopened|edited|labeled|unlabeled|assigned|unassigned|milestoned|demilestoned), issue {number, title, body, state, html_url}, plus label {name, color}, assignee {username} or milestone {title} for those actions;
  • issue_comment: action (created|edited|deleted), issue {…}, comment {id, body, html_url};
  • pull_request_review: action submitted, review {id, state, body}, pull_request {…}.

SSRF guard (mandatory)

• Resolve the host once, check every resolved address, then connect to exactly that checked address.
  • In reqwest, use a custom dns::Resolve that filters addresses, so a DNS rebind can't bypass the check.
• Reject: loopback, private (RFC1918, fc00::/7), link-local (169.254/16, fe80::/10), CGNAT 100.64/10, unspecified, multicast, broadcast, documentation ranges, IPv4-mapped IPv6 of any of these, and 0.0.0.0/8.
• Config [webhooks] allowed_hosts = [] (exact hostnames or CIDRs) whitelists internal targets; the default is empty.
• No redirects. Timeouts: 10s connect, 20s total. Response bodies are read up to 64 KiB.
• The URL must have no userinfo, and its port must be 1–65535.
• allow_http = false by default.

Delivery worker

• A tokio task started at boot. Each loop it claims due deliveries (state = 'pending' AND next_attempt_at <= now), sends them with bounded concurrency (4), and records the result.
• A 2xx response means ok.
• It is woken by a Notify when a new delivery is queued, so the first attempt is immediate; otherwise it polls every 30s.
• Deliveries older than 14 days are purged daily by the same task.

Integration points

• Enqueue through the sender-aware helpers in crates/forge-web/src/webhooks/emit.rs. Each one builds its event's payload, looks up the sender, and hands off to the generic emit(state, repo, sender, event, action, payload). That function finds the active hooks subscribed to the event and inserts a delivery for each. Nothing here fails the caller; errors are logged.
  • Sender says who made the change. lookup_sender(state, actor_id) builds one; an empty id means a system change and is sent as "sender": null.
  • emit_ref_update(…): push, plus create/delete for branch and tag creation and deletion. Only refs/heads/* and refs/tags/* produce events.
  • emit_pull(…): pull_request (for example, on PR create in pages/compare.rs).
  • emit_item_action(…): pull_request or issues action events, reloaded from the store. Used for close, reopen, merge and synchronize.
  • emit_issue(…): issues create (pages/issues_list.rs).
  • emit_label_changes(…) and emit_assignee_changes(…): one labeled/unlabeled or assigned/unassigned event per changed label (matched by name) or username. pull picks the pull_request event for a pull request and issues for an issue.
  • emit_milestone_change(…): demilestoned for the milestone before and milestoned for the one after, given their titles; nothing when they match. Same pull choice.
  • emit_comment(…): issue_comment create, edit and delete.
  • emit_review(…): pull_request_review submit.
• Call sites: post_update.rs, pulls_sync.rs, pages/{compare,issue_view,issue_parts,issue_meta,issues_list,pulls_merge,pull_reviews}.rs. The label, assignee and milestone saves in pages/issue_meta.rs run for issues and pull requests alike.
• A "ping" event is sent by emit_ping(state, hook) when a hook is created and from the "Test" button. It ignores the hook's subscriptions.

UI (repo settings, a "Webhooks" section)

• List hooks with their last delivery status.
• Create and edit form: URL, secret (write-only; leave it blank to keep the current one), event checkboxes, active.
• Delete hooks.
• Hook detail page: the last 50 deliveries, each expandable with <details> to show the request headers and body and the response; a Redeliver button and a Test (ping) button.