A webhook receipt should establish what arrived, whether it was trusted, and what processing followed. Keeping only the final database row loses the evidence needed to explain duplicate deliveries, rejected events, and partial failures.
Receipts and processing attempts are separate records
A webhook receipt represents one delivery to the application. A logical event may have multiple receipts, and one accepted event may require several processing attempts. Preserve those relationships instead of overwriting one status field repeatedly.
For a proposed ledger, record provider and account references, event identity, receipt time, verification outcome, schema version, safe processing category, and linked operation references. Keep sensitive raw payloads only when the approved purpose and policy justify them.
A receipt is not proof that a business effect completed. It may show accepted, rejected, queued, failed, uncertain, or completed processing. Those meanings need explicit definitions and timestamps.
Review a fictional duplicate notification
A customer receives two confirmation messages. The ledger shows two deliveries of the same provider event. Both were authenticated, but each created a new notification operation. That evidence points to duplicate-protection failure after ingress rather than forged traffic.
A different fixture shows one receipt with two worker attempts after a timeout. The audit should connect both attempts to the same logical operation and show whether only one external effect occurred. Overwriting the first attempt would hide the uncertainty window.
| Audit question | Ledger evidence |
|---|---|
| Did the event arrive? | Receipt reference and timestamp |
| Was the sender verified? | Safe verification result |
| Was it a repeated event? | Stable provider event identity |
| Which work executed? | Operation and attempt relationships |
| What was the final result? | Authoritative reference or explicit uncertainty |
Test malformed and unauthenticated deliveries without storing their secrets or unrestricted content. Rejected traffic still needs enough safe evidence for diagnosis and abuse review.
Protect the audit trail itself
Restrict who can read, alter, and delete receipt history. A broad support role should not automatically receive raw customer payload access. Apply retention by artifact category and keep approved deletion or exception behaviour explicit.
Detailed ledgers increase storage and schema maintenance. Minimise fields while preserving the relationships needed for actual investigations. A payload hash can assist integrity checks in a defined design, but it should not be represented as proof of sender authenticity or universal anonymity.
This ledger is proposed. The voice integration case study establishes related backend experience. Pair it with signature verification and diagnostic log selection.
Webhook receipt FAQ
Is storing the full payload always necessary?
No. Choose evidence fields according to the defined investigation purpose and data policy.
Can one event have several receipts?
Yes. Retries and redeliveries should remain connected to the same logical event.
Does a receipt marked accepted prove completion?
No. Preserve the separate processing and authoritative business-outcome states.