API Security Webhooks
A webhook is an API call that flows in reverse. Instead of a client asking for updates, the provider sends a message to a URL you own when something happens. Payment services announce completed charges, code platforms announce new commits, and shipping services announce delivered parcels. Anyone who finds your webhook URL can try to send fake messages, so receivers must verify each one.
Layman's Explanation
A courier rings your doorbell and says, "Your bank sent me with news." You would check the courier's company badge and a sealed letter before acting on the news. Webhook security supplies the badge and the seal.
Main Threats
- Forged messages that pretend to come from the provider
- Replay attacks that resend a real message again and again
- Tampering that changes the amount or status inside a message
- Overload from floods aimed at the public endpoint
- Information leaks through unencrypted delivery
Signature Verification
The provider and the receiver share a secret key. The provider computes a signature of the message body with that key, using a method called HMAC, and sends the signature in a header. The receiver repeats the calculation and compares the results.
PROVIDER RECEIVER (you)
| |
body + secret --> HMAC --> signature |
| |
| POST /webhook |
| Header: Signature = abc123 |
| Body: { "event": "paid", ... } |
| -----------------------------------------> |
| |
| body + secret --> HMAC --> signature
| |
| Does it match abc123?
| yes: process the event
| no: reject with 401
Compare signatures with a constant-time function. Normal string comparison leaks timing hints.
Stop Replay Attacks
Timestamp Checks
Providers include a timestamp inside the signed data. The receiver rejects messages older than a few minutes.
Event IDs
Each event carries a unique ID. Store processed IDs and ignore duplicates. This habit, called idempotency, also protects against honest retries that providers send after network failures.
Receiver Best Practices
| Practice | Reason |
|---|---|
| Accept HTTPS only | Encrypts data and protects the secret exchange |
| Verify the signature before parsing | Rejects forged data early |
| Return 200 quickly | Prevents provider timeouts and repeated retries |
| Process work in a queue | Keeps the endpoint fast and stable |
| Limit body size | Blocks oversized payloads |
| Use a hard-to-guess URL path | Adds a small extra barrier |
| Allow provider IP ranges when published | Narrows who can reach the endpoint |
Secret Management
Store each webhook secret in a vault. Use a different secret for each provider and each environment. Rotate secrets on a schedule. Many providers support two active secrets during a rotation window, so deliveries continue without interruption.
Validate the Content
A valid signature proves the sender, not the safety of the data. Check field types, required values, and allowed event names. Fetch critical facts, such as a payment status, from the provider's API instead of trusting the message alone.
Sending Webhooks Securely
Teams that publish webhooks carry responsibility too. Sign every message, include timestamps, retry with growing delays, and let customers rotate secrets. Block internal addresses when customers register callback URLs, since unsafe destinations create server-side request forgery risk.
Monitoring
Log each delivery with its event ID, signature result, and processing outcome. Alert on spikes in failed signatures. A burst of rejected messages often signals probing.
Handling Failures Gracefully
Providers retry failed deliveries, often for several days. Plan for retries by making every handler safe to run twice. When your system is down for maintenance, return an error code so the provider retries later, and avoid returning success without processing the event. Keep a dead-letter list of events that failed repeatedly, and review it each week so no payment or order update slips away unnoticed.
