Webhook security requires multiple controls: TLS, provider authentication/signature, replay protection, schema/size validation, rate limits, safe responses, network restrictions, and monitored recovery. IP allowlists alone are insufficient when provider ranges change or traffic passes proxies.
Verify the Request
Follow the provider’s exact scheme. Typically:
- preserve the required raw body;
- read timestamp, signature, and key identifier;
- reject timestamps outside a small tolerance;
- compute MAC/signature with the protected secret;
- compare in constant time;
- deduplicate provider event ID;
- only then parse/act.
Do not invent a generic formula or sign reserialized JSON if the provider signs raw bytes. Rotate secrets with an overlap procedure if the provider supports it.
Limit Blast Radius
Apply request-body limit, allowed content types/methods, rate/concurrency limit, strict schema, and quick rejection. Disable unused endpoints. Restrict downstream credentials. Prevent SSRF if the payload contains URLs; fetch only approved domains through a controlled service.
Store safe audit fields: request/event reference, time, verification result, reason code, source, and correlation ID—not secret/signature/full private body.
Worked Example
A synthetic payment webhook is replayed. The first verified event changes payment from PENDING to PAID after server-side amount/currency/reference checks. The second has the same provider event ID and returns a no-op.
An attacker changes the amount without recomputing the signature: verification fails. A valid signed event with wrong amount enters reconciliation, not fulfillment. A burst triggers rate control and alerting.
The reconciliation record identifies the provider event and exact mismatch while excluding full credentials, signatures, and unnecessary customer payload data from general logs.
Failure Cases to Diagnose
- Signature compared as ordinary string: use constant-time comparison.
- Timestamp ignored: captured signed request can replay.
- Body parsed before raw verification: signature may no longer match.
- Valid signature equals valid business event: validate amount/state/reference too.
- Secrets logged during debugging: rotate and scrub access.
- Endpoint accepts GET and POST: allow only contract method.
🇵🇰 Pakistan Angle
For SWICH, wallets, banks, couriers, or telecom providers, use their current official verification and inquiry documentation. Never trust a customer screenshot or payment-result redirect as settlement.
Local provider outages should open a reconciliation queue with PKT owner and case reference. Do not weaken signature or replay checks to “keep sales moving.”
Hands-On Exercise
- Write one provider verification contract.
- implement raw-body/timestamp/signature checks in a trusted boundary.
- add event deduplication and business validation.
- test replay, tamper, old timestamp, burst, and wrong amount.
- run secret rotation drill.
Completion Rubric
- Verification matches official provider scheme.
- Timestamp and event replay are checked.
- Comparison and secret handling are safe.
- Schema, size, method, and rates are bounded.
- Business state validates independently.
- Rotation, alerts, and reconciliation operate.
Sources
Key takeaway: authenticate raw requests, reject replay, validate business truth, limit abuse, and preserve a monitored reconciliation path.