Architecture Decision Record Skill: Immutable MADR Format

Proposed → Accepted → (Deprecated) → (Superseded by ADR-NNN)

# ADR-0007: Use HMAC-SHA256 for Webhook Request Signing

**Status:** Accepted
**Date:** 2026-07-17
**Author:** [Name]
**Deciders:** [Engineering Lead, Security Lead]
**Technical Story:** [Link to issue #142]
**Review Date:** 2027-01-17

---

## Related ADRs

| ADR | Relationship | Notes |
| :--- | :--- | :--- |
| ADR-0003 | Influenced by | Authentication strategy for API endpoints |

---

## Context

Our webhook delivery system must authenticate outbound HTTP notifications to
merchant endpoints so merchants can verify requests originate from us. We
deliver approximately 2M events/day to ~8,000 merchant endpoints. Merchants
implement their verification logic in a variety of languages (PHP, Node, Python,
Ruby). The verification mechanism must be straightforward to implement in any
language without a dedicated SDK.

---

## Decision

**We will sign webhook payloads using HMAC-SHA256 with a per-merchant secret.**

The signature is computed over the raw request body and transmitted in a
`X-Signature-SHA256` header. Merchants verify the signature by computing
HMAC-SHA256 with their stored secret and comparing the result. A timestamp
header (`X-Timestamp`) is included; signatures older than 5 minutes are rejected
to prevent replay attacks.

---

## Rationale

HMAC-SHA256 with a static per-merchant secret requires no token rotation
infrastructure and is trivially implementable in any language using standard
library crypto primitives. The payload integrity guarantee (signature covers
the full request body) exceeds what bearer tokens provide.

---

## Alternatives Considered

### Option 1: Bearer tokens (rotating JWT)

**What it is:** Each merchant receives a rotating JWT. We include the token
in the Authorization header. Merchants verify the token against our JWKS
endpoint.

**Why it was rejected:**
- Requires merchants to implement token refresh logic; significantly increases
  integration complexity for simple use cases.
- Introduces a dependency on our JWKS endpoint availability during webhook
  processing — if our JWKS endpoint is down, merchants cannot verify webhooks.
- Does not provide payload integrity — a MITM could modify the body while the
  token remains valid.

**What we lose by not choosing it:** Standardized OAuth2/JWT ecosystem tooling.

---

### Option 2: Mutual TLS (mTLS)

**What it is:** Merchants present a client certificate; we verify it before
delivering the webhook.

**Why it was rejected:**
- Certificate provisioning and rotation is operationally complex for merchants,
  especially small businesses with no dedicated infrastructure team.
- Incompatible with our target of easy onboarding in < 15 minutes.

**What we lose by not choosing it:** Stronger transport-layer identity guarantee.

---

## Consequences

### Positive Consequences

- No token rotation infrastructure required on either side.
- Implementable in < 20 lines in any language; reduces merchant integration time.
- Payload integrity validated — tampering invalidates the signature.
- Replay attack window closed by 5-minute timestamp validation.

### Negative Consequences / Trade-offs

- Per-merchant secret must be securely stored on our side (encrypted at rest).
- If a merchant's secret is compromised, all their webhooks are at risk until
  secret rotation is triggered.
- No centralized revocation — secret rotation requires merchant action.

### Risks Introduced

| Risk | Probability | Impact | Mitigation |
| :--- | :--- | :--- | :--- |
| Secret compromise via merchant-side storage | Medium | High | Force HTTPS delivery; provide secret rotation endpoint; alert on unusual delivery patterns |
| Clock skew > 5 min between our infra and merchant | Low | Medium | Use NTP; allow ±5 min window with clear error message for out-of-window requests |

---

## Assumptions That Could Invalidate This Decision

| # | Assumption | How to Verify | Consequence If False |
| :--- | :--- | :--- | :--- |
| 1 | Merchants can store a static secret securely | Integration audit | Need to evaluate certificate-based auth |
| 2 | 5-minute timestamp window is sufficient for all merchant infra | Monitor timestamp deltas in delivery logs | Adjust window or implement NTP requirement |

---

## References

- [Stripe webhook signing documentation](https://stripe.com/docs/webhooks/signatures)
- [GitHub webhook signing](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries)