Commit ea02c54
DzEuSkiNG
docs: add webhook debugging guide
Practical debugging guide for merchants and operators implementing or
diagnosing webhook receivers. Complements docs/WEBHOOKS.md (reference)
and docs/MERCHANT_COOKBOOK.md (end-to-end recipes).
Sections:
- Webhook model overview (22 events, retry constants, lifecycle)
- Headers and signature contract (exact algorithm + legacy v1 note)
- Golden rule: verify against raw body (framework checklist)
- Signature verification examples (Python, Node.js, PHP, OpenSSL)
- Receiver skeletons (FastAPI, Express w/raw middleware, PHP)
- Idempotency handling
- Delivery failures and retries (DLQ flow)
- Debugging signature failures, missing webhooks, duplicates
- Event-specific debugging
- Curl recipes (placeholders only)
- Safe logging and redaction
- Issue checklist
Source verification:
- HMAC-SHA256 algorithm: utf8(ts) + b'.' + utf8(did) + b'.' + raw_body
- 6 X-GhostBill-* headers match webhook_service.py exactly
- Constants MAX_ATTEMPTS=7, DELIVERY_TIMEOUT=10s, RETRY_DELAYS list
identical to webhook_payloads.py
- Success criteria 2xx (200-299) matches webhook_service.py
- All examples use placeholders only; no real secrets or domains1 parent 7f735d7 commit ea02c54
1 file changed
Lines changed: 593 additions & 0 deletions
0 commit comments