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.

// concept

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.

// concept

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

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

Failure Cases to Diagnose

6 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

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

Hands-On Exercise

5 steps

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

Completion Rubric

6 checks — tick as you verify

0/6

// sources

Sources

3 official sources — check every claim yourself

// check_yourself

Check yourself

4 questions · answers and options are taken word-for-word from this course

0/4

1 / 4 · diagnose
Your work shows this failure mode: “Signature compared as ordinary string.” What does the lesson tell you to do about it?