Skip to main content

​
Context

Customers receive events from Stackra by webhook. The design ADR that 0078 promised was never written, and the owner’s webhook answers WH1 to WH4 (mem L748–751, L502, 2026-10-20) fix it. Webhooks are a separate logical service from integrations.

​
Decision

  1. What is delivered (WH1). Only public, versioned integration events, filtered by scope.
  2. Format (WH2). The Standard Webhooks specification: HMAC-SHA256 signatures, optional ed25519, and dual-secret rotation. A thin mode sends personal-data events with the minimum fields.
  3. Delivery (WH3). At-least-once delivery, retried for about three days. A subscription that keeps failing is disabled automatically. FIFO is optional. A portal shows the deliveries, with replay and a dead-letter queue. The native driver is the default. Convoy (MPL-2.0) is the high-volume option.
  4. Inbound (WH4). One inbound gateway verifies provider webhooks. Raw payloads are kept for 30 days.
  5. Boundary. Webhooks are a separate service from integrations (ADR 0218).

​
Consequences

  • A receiver verifies every delivery with its own secret, so a forged request fails.
  • A thin payload for personal data keeps personal information out of a third party’s logs.

​
Enforcement

planned — the signature test runs against the Standard Webhooks test vectors; the delivery test covers retry, disable and replay.

​
Supersedes and sources

Supersedes: none. Sources: owner webhook answers WH1–WH4 (stackra-decisions-2026-10-19.md L502, L748–751, 2026-10-20). Builds on 0078.