---
title: blog-topic / webhook-signature-replay-contract
source_type: blog-topic
status: raw
related_branches: [feature-webhook-outbound-contract]
related_projects: [ca-tmpl]
tags: [blog-topic, ca-tmpl, integration, security, api-contract, retry-policy, event-schema]
created: 2026-07-02
status_label: ready-for-canonical
target_audience: backend-engineer
inspiration_url:
archive_url:
---

# blog-topic: webhook-signature-replay-contract

> Layer: `raw/blog-topics/` — 작업 중 나온 블로그 글감 원석. 최종 블로그는 canonical 정제 후 `wiki/blog/`에서 작성한다.

## Parent / 부모

- [[raw/branch-notes/feature-webhook-outbound-contract]] — HMAC signature와 replay protection contract 결정에서 나온 글감.

## 트리거 / Trigger

- 트리거 유형: `branch-work`
- 트리거 날짜: 2026-07-02
- 트리거 연결 노트: [[raw/branch-notes/feature-webhook-outbound-contract]]

## 글감 / Topic seed

- 한 문장 요지: webhook signature에서 raw bytes, timestamp, message id를 계약으로 고정하고 replay window를 다루는 방법을 정리한다.
- 예상 제목 후보:
  - Webhook HMAC signature에서 무엇을 서명해야 할까
  - replay protection은 signature와 별개로 설계해야 한다

## 핵심 주장 후보 / Claim candidates

- 사실 후보:
  - branch D1/D2가 signature/replay contract를 다룬다 — 근거 후보: [[raw/branch-notes/feature-webhook-outbound-contract]] line `:98-109`, `:147-157`.
- 경험 후보:
  - header명과 Hex 인코딩은 project-local convention으로 두고, raw bytes/timestamp/message id 같은 핵심은 source-backed 결정과 분리해야 한다.
- 의견/해석 후보:
  - HMAC signature는 payload integrity만 다루므로, replay 방지는 timestamp/window/message id 저장 정책과 함께 설계해야 한다.

## Outline seed

1. canonical string을 정하지 않으면 signature가 흔들린다 — raw bytes, timestamp, id를 어떤 순서로 묶을지 정한다.
2. signature와 replay는 다른 문제다 — 같은 요청을 다시 보내는 공격은 별도 state/window가 필요하다.
3. provider convention과 project convention 분리 — Stripe/Svix/GitHub 사례를 그대로 표준처럼 쓰지 않는다.

## Canonical 전환 후보 / Canonical extraction candidates

- `wiki/projects/ca-tmpl/data-layer-persistence-cache-outbound.md` 후보:
  - ca-tmpl outbound webhook signature/replay contract.
- `wiki/concepts/webhook-signature.md` 후보:
  - webhook HMAC signature와 replay protection 일반 개념.
- 필요한 추가 검증:
  - raw body access, timestamp tolerance, message id dedupe storage.

## Sources / 근거 후보

- [[raw/branch-notes/feature-webhook-outbound-contract]] — D1/D2 signature/replay 근거.
- [[raw/official-docs/github-webhook-signature]] — provider signature 근거 후보.
- [[raw/official-docs/stripe-webhook-signature]] — provider signature 근거 후보.
- [[raw/official-docs/svix-webhook-best-practices]] — webhook best practice 근거 후보.

## 미해결 / Unknown

- 아직 확인해야 할 사실: ca-tmpl의 exact header names, encoding, replay store 구현 여부.
- 과장하면 안 되는 부분: provider 문서를 universal standard처럼 쓰지 않는다. 사례와 project convention을 분리한다.
- 블로그로 쓰기 전에 필요한 canonical 정제: signature concept 문서와 project decision 분리.

## Decision / 처리 결정

- 액션: `promote-to-canonical`
- 이유: `wiki/projects/ca-tmpl/data-layer-persistence-cache-outbound.md` 에 webhook signature/replay 글감으로 반영했다.
- 다음 단계: target canonical이 아직 `draft` 이므로 `blogify` 전 review/verify가 필요하다. provider 문서를 universal standard처럼 쓰지 않는다.

## Related / 관련

- 관련 branch: [[raw/branch-notes/feature-webhook-outbound-contract]]
- 관련 error:
- 관련 interview prep:
- derived blog: 생성 전. 생성 시 `wiki/blog/webhook-signature-replay-contract-YYYY-MM-DD.md` 후보