Skip to content

Commit ea02c54

Browse files
author
DzEuSkiNG
committed
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 domains
1 parent 7f735d7 commit ea02c54

1 file changed

Lines changed: 593 additions & 0 deletions

File tree

0 commit comments

Comments
 (0)