Docs

Receiving Webhooks Through the WAF

Overview

Webhooks are automated notifications that outside services (Stripe, GitHub, Slack, payment gateways, monitoring tools) POST to your application when something happens on their end. They are some of the most important traffic your application receives, and also some of the most likely to be blocked by a WAF. This guide explains why, how to set up webhook endpoints correctly before you go live, and what a webhook block looks like when it happens.

Why Webhooks Look Like Attacks

Webhook traffic has almost every characteristic the WAF treats as a risk signal:

  • They are POST requests. POSTs carry a request body, so they get stricter security inspection than GETs. Most application attacks (injection, exploit payloads, spam) arrive as POSTs.
  • They arrive in bursts. A batch of events, or a retry cycle after a failed delivery, can produce dozens of requests to the same URL within a few seconds. That volume pattern matches automated attack tools.
  • They come from data center IPs. Webhook senders run at cloud hosting providers, and those same networks originate a large share of real attack traffic. A data center IP carries a worse reputation score than a residential one.
  • Their payloads can match attack signatures. JSON containing SQL keywords, HTML fragments, or encoded data can resemble injection attempts.
  • They have no browser signals. No cookies, no prior page views, and a non-browser user agent, the same profile as a scripted attack.

None of this means anything is wrong with the sender. It means a webhook endpoint needs an explicit exception before the traffic starts.

Set Up Before You Go Live

1. Allowlist the Sender’s IP Addresses

If the sending service publishes fixed source IPs (payment gateways almost always do, and most webhook providers document theirs), add them under Traffic Rules > Allow IPs. Allowlisted IPs bypass WAF filtering entirely, so bursts and payload contents from that sender will never trigger a block.

This is the preferred approach for webhooks. The exception applies only to the sender, and your endpoint stays protected against everyone else.

If you have many IPs or ranges to add, see Bulk IP Allowlisting and Blocklisting.

2. Or Allowlist the Path, If Sender IPs Rotate

Some services deliver from changing or very large IP ranges. In that case, allowlist the endpoint path instead under Path Rules > Allow, using an Equals match on the exact path (for example /api/webhooks/stripe). See Allowlisting URL Paths.

Be aware of the tradeoff: a path allowlist exempts the endpoint for every source, so attackers can probe that URL without WAF inspection. Your application must validate webhook signatures on an allowlisted path. Nearly all webhook providers sign their deliveries; verify the signature and reject anything unsigned.

3. Check the HTTP Method and Payload Size

POST is always permitted, but if the sender uses PUT or DELETE, confirm the method is enabled under Traffic Rules > HTTP Methods. If deliveries include large payloads, confirm they fit within your maximum request size.

What a Blocked Webhook Looks Like

Webhook blocks are easy to misdiagnose because the sender, not a person, sees the error. Watch for these patterns:

403 responses. The delivery fails and the sending service records a 403 error. These blocks appear in your Block Logs with a reason code. See the Block Codes Reference.

Silent outages after a burst. If a burst of deliveries trips intrusion detection, the WAF can temporarily ban the sender’s IP at the network edge. The first few requests get 403 responses and show up in your block logs. After that, connections from the IP are dropped with no HTTP response at all, and those dropped connections are not logged. To the sending service, your server appears unreachable for roughly 20 to 35 minutes. There is no 429 and no log entry for the gap; the only evidence is the small cluster of 403 entries at the start.

Repeating outage windows. Senders retry failed deliveries on a schedule. Each retry burst can trigger the ban again, so you may see the same outage repeat at regular intervals until the sender’s IP is allowlisted.

If deliveries are failing and you are not sure why, Troubleshooting API Blocks walks through diagnosis step by step.

Verify Your Setup

  1. Most services can send a test delivery from their dashboard (Stripe and GitHub both offer this). Trigger one.
  2. Check your Block Logs for any entry matching the sender’s IP or your endpoint path. An allowlisted sender should produce none.
  3. Confirm the delivery arrived in your application’s own logs.

Need Help?

If webhook deliveries are still failing or you want us to review your endpoint configuration: