참고 자료 · 54
웹훅: 반복, 지연 및 복구 처리
수신된 알림을 장애 발생 후 복구 가능한 고유하고 추적 가능한 비즈니스 효과로 변환합니다.
업데이트됨 · 18 min
이 가이드가 달성하는 목표
- 알림 인증
- 영수증과 처리 분리
- 중복 영향 방지
- 차단된 이벤트 복구
빠른 확인
- 어떤 바이트가 서명되었습니까?
- 영수증은 언제 영구적입니까?
- 두 워커가 함께 작업할 수 있습니까?
- 공급자가 순서를 보장합니까?
- 손실된 이벤트를 어떻게 찾습니까?
단계별 방법
- 1
공급자 계약 읽기
유형, 버전, 계정 컨텍스트, 서명, 타이밍 및 재시도 규칙 기록. Stripe는 전달 순서가 보장되지 않으며 중복이 발생할 수 있다고 명시합니다. 모든 API에 Stripe 관련 지연을 적용하지 마십시오.
제공물: 날짜가 포함된 공급자 계약.
- 2
효과 발생 전 유효성 검사
공급자가 요구하는 라이브러리 및 원시 본문을 사용하여 서명을 확인합니다. 허용되는 크기와 유형을 제한합니다. 비밀 키를 로깅하지 않고 승인된 환경에서 유효하지 않은 서명과 예상치 못한 계정 컨텍스트를 테스트합니다.
결과물: 영향 없는 거부.
- 3
승인 전에 데이터를 보존합니다.
내구성 있는 수신과 느린 처리를 분리합니다. 큐가 이벤트를 수락할 수 없는 경우 보존된 것으로 보고하지 않습니다. 성공은 계약에 따른 수신을 의미하며, 비즈니스 작업 완료를 반드시 의미하는 것은 아닙니다.
결과물: 수신됨, 처리 중, 완료됨 및 차단됨 상태.
- 4
멱등성을 적용합니다.
이벤트 키와 비즈니스 효과의 동일성을 정의합니다. 순차적 전달뿐 아니라 동시 반복을 테스트합니다. 원자적 제약 조건이나 잠금 없이 사전 검사를 수행하면 두 작업자가 동일한 효과를 생성할 수 있습니다.
결과물: 효과 고유성 증거.
- 5
지연 및 무질서 처리.
이전 알림이 현재 상태를 설명한다고 가정하지 않습니다. 계약에서 허용하는 경우 소스를 참조하고 검증된 비즈니스 전환을 적용합니다. 아직 해석할 수 없는 이벤트를 보존합니다.
산출물: 전환 및 역순 테스트
- 6
조정 및 재실행
소유자, 원인, 시도 횟수 및 종료 시점을 포함하는 오류 큐 준비. 재실행 중 중복 방지 유지. 공급자와 애플리케이션을 주기적으로 비교: 복구 성공이 이벤트 누락이 없음을 증명하는 것은 아님.
산출물: 복구 절차 및 불일치 보고서
재사용 가능한 워크시트
승인된 의견을 기입하십시오. 이 항목들은 작업 템플릿이며, 관찰된 결과가 아닙니다.
| 필드 | 기록할 정보 |
|---|---|
| 이벤트 | 공급자, 계정, 식별자 및 버전 |
| 영수증 | 유효성 검사된 서명 및 영구 타임스탬프 |
| 영향 | 비즈니스 키, 상태 및 고유성 증거 |
| 복구 | 원인, 시도, 담당자 및 종료 |
가상 예시
예시 상황
가상 예시입니다. 고객이나 실제 관측 결과를 나타내지 않습니다. 같은 결제 알림이 두 번 도착하고, 처리 과정에서 하나의 구독을 두 번 활성화하려 합니다.
결정 및 예상 증거
진위를 확인하고 중복을 식별합니다. 청구서와 구독 상태를 권한 있는 원본과 대조합니다. 업무 효과가 한 번만 발생했는지 확인하고 비밀정보 없이 중복을 기록합니다. HTTP 수신 확인만으로 올바른 활성화를 입증할 수는 없습니다.
메커니즘 구분
| 메커니즘 | 목적 | 검증 또는 제한 |
|---|---|---|
| 서명 | 계약에 따른 출처 유효성 검사 | 효과가 고유하지 않음 |
| 중복 제거 | 반복 알림 인식 | 동시성 및 비즈니스 효과 확인 |
| 조정 | 누락 및 차이점 찾기 | 소스 및 기간 명시 |
관리 지표
| 지표 | 측정 대상 | 첫 번째 조치 |
|---|---|---|
| 큐 경과 시간 | 미완료 이벤트 지연 | 가장 오래된 이벤트 검사 |
| 중복 효과 | 오류로 반복된 비즈니스 작업 | 원자성 수정 |
| 소스/애플리케이션 격차 | 부재 또는 불일치 상태 | 종료 증거와 조정 |
일반적인 실수
- 서명된 본문 검증 전 구문 분석
- 영구 수신 전 승인
- 순차적 전달 가정
- 중복 항목은 순차적으로만 테스트
자주 묻는 질문
HTTP 성공은 처리 완료를 의미하는가?
계약에 따라 다릅니다. 비동기 처리의 경우, 비즈니스 상태는 별도로 추적되는 동안 영구적인 수신이 보장되어야 합니다.
정확히 한 번만 배송이 보장될 수 있습니까?
실제 계약 상황에서 반복 및 실패를 고려하여 설계하되, 고유한 효과와 조정이 가능하도록 해야 합니다.
전체 내용을 보관해야 합니까?
적절한 접근 권한과 보존 기간을 두고 필요한 경우에만 보관해야 합니다. 최소한의 흔적만 남겨 비밀 정보를 보관하지 않고도 진단 및 복구를 지원해야 합니다.
멱등성과 API 재시도 계약
이 언어판의 상세 참고 설명은 영어로 제공됩니다.
Separate request retries from notification repeats
An outgoing API request key, a received-event identifier and a business-effect identity serve different roles.
- Define provider, account, event and effect before selecting a deduplication key.
- Test concurrent workers and an unknown external-effect outcome.
- Reconcile business state with the source; a valid signature does not make processing unique.
Compare idempotency contracts →
References reviewed · RFC 9110 · §9.2.2, §10.2.3 · RFC 6585 · §4 · Stripe
웹훅: 서명과 재전송
이 언어판의 상세 참고 설명은 영어로 제공됩니다.
Authenticate a delivery, retain the event and control its effect
A webhook signature answers a specific question: do the received bytes match those authenticated with the expected key? It guarantees neither freshness nor uniqueness nor successful business processing. Separate these decisions in the receipt contract so that the integration can be observed and recovered.
The signature and recovery rules below belong to the cited Stripe and GitHub contracts. The timeline and ten cases are fictional exercises; this page activates no endpoint, real secret or payment mechanism. Use official libraries and test the relevant provider configuration for a real integration.
Stripe and GitHub: six differences to retain
| Control | Stripe | GitHub |
|---|---|---|
| Signature header | Stripe-Signature contains t and one or more v1 signatures. The documented active scheme is v1. | X-Hub-Signature-256 contains a SHA256 HMAC prefixed with sha256=. |
| Authenticated message | Text timestamp, a period and the raw body: timestamp + "." + body. | The raw delivery body. Transport headers are not added to this HMAC message. |
| Freshness and replay | The timestamp is authenticated. Documentation states a five-minute default tolerance in its libraries; each retry receives a new timestamp and signature. | The body HMAC alone provides no freshness proof equivalent to Stripe’s timestamp. Plan duplicate detection and recovery according to the contract. |
| Identity to track | event.id identifies repeated delivery. Stripe also describes distinct events that may require correlation using data.object.id and event.type. | X-GitHub-Delivery identifies the delivery; requested redelivery retains that identifier. Its value remains outside the body authenticated by the HMAC described here. |
| Delivery failure | Live-mode automatic retries for up to three days with exponential backoff. A manual resend does not automatically cancel these retries. | GitHub does not automatically redeliver failures. Arrange manual redelivery or application-managed recovery using the available APIs. |
| Fast acknowledgement | Return a 2xx quickly, before lengthy work. Durable receipt before acknowledgement is the architectural policy of our exercise. | Respond with 2xx within ten seconds according to the documentation. A queue separates receipt from business processing. |
Retain three separate identities
| Identity | Fictional example | Purpose and limit |
|---|---|---|
| Transport attempt | delivery_attempt_02 | One event can arrive several times. An attempt’s timestamp and signature are not a business key. |
| Provider event | provider + account + environment + evt_training_001 | Recognise the same event within its scope. Define retention and recovery behaviour; a bare identifier without context may be insufficient. |
| Business effect | tenant_7 + case_42 + initial_activation | Prevent a second initial activation here. The key belongs to this operation; do not discard all future object updates by reducing them to the object identifier alone. |
Three bodies, six HMACs: what reformatting changes
Public exercise-only key: training-only-key-not-a-secret. Fixed timestamp: 1792663200, corresponding to 2026-10-22 at 10:00:00 UTC. Strings use UTF-8 with no trailing newline. A and B represent the same JSON object but have different bytes; C changes case_42 to case_43.
| Body | UTF-8 bytes | Exact string, written as a JSON string |
|---|---|---|
| A | 68 | "{\"id\":\"evt_training_001\",\"type\":\"evidence.ready\",\"object\":\"case_42\"}" |
| B | 73 | "{\"id\": \"evt_training_001\", \"type\": \"evidence.ready\", \"object\": \"case_42\"}" |
| C | 68 | "{\"id\":\"evt_training_001\",\"type\":\"evidence.ready\",\"object\":\"case_43\"}" |
| Body / scheme | Message used | Calculated hexadecimal HMAC-SHA256 |
|---|---|---|
| A · GitHub | body | d6ac0a608c901617782f3b7aef64198718e3affd410a219b22b84da008235364 |
| A · Stripe v1 | timestamp + "." + body | 0ad9c9f7c0df2d8a8265113e641d92f57ce0dffd703a7cf9f13c4163e21bf6dc |
| B · GitHub | body | c9c47b1432282b9a3c2cbf4aded2c750deed235ac948dffe248488b84a4af73d |
| B · Stripe v1 | timestamp + "." + body | 0ad8e262a5870766d4cce864f50a5feac65a3004e3c3208184da9cc075c7abd6 |
| C · GitHub | body | 55162fc08e3cb0efd0eb082978ba61a88cf3624ffc5322f19ab73d91466a616d |
| C · Stripe v1 | timestamp + "." + body | d7f4014489a900399a7049daa3e8f1ce2b208bf95b93c43492cb68f7d6f1b791 |
These results use the documented message constructions with a publicly displayed key and invented data. They are not authentic Stripe or GitHub deliveries. Different JSON serialization, even if semantically equivalent, must not replace the original body before verification. In production, compare in constant time and manage key rotation according to the selected library and contract.
Stripe tolerance parameter: the value 0 disables recency checking in the libraries described by its documentation. It does not mean “accept only the exact second”. Do not transfer the OAuth/OIDC example’s clock policy to this parameter.
Seven records for one local effect
Fictional scenario on 2026-10-22, all times UTC. Authenticate before admission and persist receipt before responding. An atomic constraint protects initial activation in the same database as its business state. Counts below are calculated for this exercise and describe no client outcome.
| UTC time | Observed signal | Scenario decision | Cumulative local effects |
|---|---|---|---|
| 10:00:00 | evt_training_001 admitted; response lost | Durable receipt, pending state; no business effect executed yet. | 0 |
| 10:00:01 | Worker A claims the event | Atomic work reservation; processing state. | 0 |
| 10:00:01 | Worker B sees the same event | Do not create a second processing owner or execute again. | 0 |
| 10:00:02 | Worker A commits the local transaction | Atomically write initial activation and its completed state. | 1 |
| 10:00:03 | New delivery of evt_training_001 | Authenticate the new attempt, find the completed event and acknowledge without a second effect. | 1 |
| 10:00:04 | evt_training_002 targets the same initial activation | Retain the distinct event; this business-operation key already exists. | 1 |
| 10:00:05 | evt_training_003 carries an earlier state | Reject a regressive transition under the exercise policy and reconcile the source. | 1 |
The transaction described protects a local effect. It does not make an external service call atomic. After an unknown external result, retain uncertainty, query the source and apply the available idempotency mechanism before retrying. A transactional outbox can organise emission; it does not establish a universal exactly-once guarantee.
Ten denial and recovery tests to prepare
01 · Invalid signature: no effect
Present a delivery whose HMAC does not match the received body.
Expected: reject before admission and any effect. Retain a redacted reason and configuration version, without recording the key, token or sensitive body content.
02 · Reformatted JSON with the original signature
Replace A with B while keeping the signature computed for A. Both JSON strings decode to the same object.
Expected: verification failure. Capture the raw body at the right framework stage; do not try different reformattings to recover the signature.
03 · Correct signature, stale timestamp
In a Stripe test, authenticate a 09:50:00 timestamp while the acceptance-test clock is 10:00:00, with a configured five-minute tolerance.
Expected: reject freshness despite a correct HMAC. Separate message integrity, delivery age and event creation age.
04 · Same event, newly authenticated attempt
Receive two deliveries of the same event.id; the Stripe retry has its own timestamp and signature.
Expected: authenticate each attempt, then find durable state. A different signature does not justify a second business effect.
05 · Two events, one initial activation
Receive two event identifiers requesting the same fictional initial activation of case_42.
Expected: record both events and protect this operation with its business key. Do not apply this rule blindly to legitimate successive updates of the same object.
06 · Two workers at the same instant
Start two workers on the same pending item in the authorised test environment.
Expected: atomic acquisition and one effect transaction. “Read absent, then insert” without a constraint can allow both workers through; inspect business results, not logs alone.
07 · Queue unavailable before acknowledgement
Simulate queue or database failure before receipt has been durably confirmed.
Expected under our architecture: do not acknowledge as though the event were retained. Exercise the provider’s recovery strategy; GitHub does not automatically redeliver failures.
08 · Response lost after durable receipt
Drop the response after notification persistence; let processing continue under the exercise policy.
Expected: the next attempt finds pending, processing or completed state. The sender may not know receipt succeeded; network uncertainty must not duplicate the effect.
09 · Old event after a newer state
Deliver a notification with an earlier state after a newer notification.
Expected: apply permitted business transitions and reconcile current state when necessary. A fresh signing timestamp can carry an old event; it does not prove business-state novelty.
10 · Manual recovery overlaps automatic retry
Send manual recovery and Stripe automatic retry towards the same event.
Expected: both paths use the same concurrency and idempotency controls. A successful manual resend does not itself cancel automatic retries; verify closure with the provider.
Six useful operating records
- Dated provider contract: environment, account, type, version, signature, timing and recovery.
- Redacted admission trace: internal reference, verification result, clock and policy version.
- Durable event state, work owner and evidence that the uniqueness constraint was tested.
- Effect identity and legitimately repeatable operations; separate the event from the business object.
- Failure queue with cause, attempt count, owner, next action and verified closure.
- Source/application reconciliation over a defined period, including never-received notifications and uncertain external effects.
Provider contracts and primary sources
- Stripe · Webhooks · Living documentation · reviewed 2026-10-22
Event delivery behaviors · Handle duplicate events · Verify manually · Preventing replay attacks - Stripe · Manage webhook endpoints · Living documentation · reviewed 2026-10-22
Process undelivered events · Resolve signature verification errors - GitHub · Validating webhook deliveries · Living documentation · reviewed 2026-10-22
HMAC-SHA256 · X-Hub-Signature-256 · raw payload · constant-time comparison - GitHub · Best practices for using webhooks · Living documentation · reviewed 2026-10-22
Respond within 10 seconds · X-GitHub-Delivery · redelivery retains the identifier - GitHub · Handling failed webhook deliveries · Living documentation · reviewed 2026-10-22
No automatic redelivery · manual or application-managed recovery
Sources reviewed on
API 오류: 유형, 상태 및 증거
이 언어판의 상세 참고 설명은 영어로 제공됩니다.
An error response establishes neither failure nor safe replay
After interruption or an inconsistent response, a call may have produced an effect. Problem Details improves description; it does not prove no processing occurred or provide a universal retry policy.
- Preserve HTTP status, received body and permitted operation identifier in controlled traces.
- Check business state and idempotency rules before repeating an action.
- Test public messages without exposing secrets, internal paths or account details.
Explore problem types and eight fictional responses →
IETF · M. Nottingham, E. Wilde, S. Dalal · RFC 9457 · July 2023 · obsoletes RFC 7807 · §3.1, §3.2, §4.2, §5
공식 참조
참조는 방법을 뒷받침합니다. 상황에 맞게 검사를 조정하십시오. 이는 인증이 아닙니다. 원본 참조 제목 및 소스 문서는 다른 언어로 작성되었을 수 있습니다.
참고 자료 확인일 .
- Stripe — Webhooks
- Stripe — Process undelivered webhook events
- GitHub · Validating webhook deliveries
- GitHub · Best practices for using webhooks
- GitHub · Handling failed webhook deliveries
- IETF · M. Nottingham, E. Wilde, S. Dalal · RFC 9457
- IETF · RFC 9110 — Retry-After et idempotence HTTP
- IETF · RFC 6585 — 429 Too Many Requests
- AWS Builders’ Library · Timeouts, retries, and backoff with jitter
- Stripe · Idempotent requests
- Stripe · API v2 overview — Idempotency
- Stripe · Advanced error handling
