Payment webhook audit log in Next.js
A buyer, founder, or support lead will eventually ask what happened to a checkout, refund, or renewal. An audit log turns billing webhook behavior into evidence instead of guesswork.
Rows to capture
Record provider, event ID, event type, object ID, customer reference, raw body hash, and signature verification result.
Record the idempotency key, first-seen timestamp, duplicate replay count, and whether side effects were skipped.
Record grant, extend, hold, revoke, refund rollback, ignore, or quarantine decisions with the policy version used.
Record outcome, replay command reference, and next action without exposing API keys, webhook secrets, private checkout links, or full customer data.
Next.js table shape
A minimal audit table should explain the event, the trust gate, the business decision, and the side effects. Keep secrets out of rows you export to PRs or support tickets.
create table payment_webhook_audit_log (
id text primary key,
provider text not null,
event_id text not null,
event_type text not null,
object_id text not null,
raw_body_sha256 text not null,
signature_verified boolean not null,
idempotency_key text not null,
entitlement_decision text not null,
side_effect_status text not null,
support_note text not null,
created_at timestamptz not null default now()
);CI gates
- Signed checkout fixture writes one audit row with
signature_verifiedtrue. - Duplicate replay increments or records replay evidence without repeating fulfillment.
- Refund fixture records rollback decision and support-safe note.
- Unknown event records quarantine decision without running entitlement writes.
- Exported review report contains no API keys, webhook secrets, full customer records, or private checkout links.
FAQ
What should a payment webhook audit log store?
Store provider, event ID, event type, object ID, raw body hash, signature result, idempotency key, entitlement decision, side-effect status, and support-safe notes.
Should webhook audit logs store raw payloads?
Store raw payloads only if your privacy policy and retention rules allow it. A raw body hash plus fake fixtures is often enough for public release evidence.
Turn audit rows into release evidence
The free test plan and entitlement matrix tools help define audit rows. The CNY 69 Pro Kit is for teams that want fixtures, idempotency tests, review templates, and launch runbooks already packaged.