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

PracticeReason
Accept HTTPS onlyEncrypts data and protects the secret exchange
Verify the signature before parsingRejects forged data early
Return 200 quicklyPrevents provider timeouts and repeated retries
Process work in a queueKeeps the endpoint fast and stable
Limit body sizeBlocks oversized payloads
Use a hard-to-guess URL pathAdds a small extra barrier
Allow provider IP ranges when publishedNarrows 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.