This guide covers everything you need to test Cloudflare webhooks — how to inspect the raw payload, verify the signature, forward events to localhost, and reproduce any delivery in your local development environment without needing a real Cloudflare event.
How to Test Cloudflare Webhooks with WebhookWhisper
- Create a free endpoint — click Create Live Endpoint above to get a permanent public HTTPS URL (no account required to try)
- Register the URL in Cloudflare — paste the WebhookWhisper URL into Cloudflare's webhook settings
- Trigger a test event — use the one-click test payload sender or trigger a real event in Cloudflare
- Inspect the request — see the full headers, raw body, and Cloudflare signature header in real time
- Forward to localhost — add a forwarding rule to relay the event to your local handler (e.g.
http://localhost:3000/webhooks/cloudflare)
Cloudflare Webhook Signature Verification
Cloudflare signs webhook deliveries using Bearer token. The signature is sent in the Cf-Webhook-Auth header. Always verify this signature before processing the payload to ensure the request came from Cloudflare and was not tampered with in transit.
Node.js Verification
const crypto = require('crypto')
const express = require('express')
const app = express()
app.post('/webhooks/cloudflare',
express.raw({ type: 'application/json' }),
(req, res) => {
const secret = process.env.CLOUDFLARE_WEBHOOK_SECRET
const signature = req.headers['cf-webhook-auth']
// Compute expected HMAC — always use raw body, never parsed JSON
const expected = crypto
.createHmac('sha256', secret)
.update(req.body)
.digest('hex')
if (!crypto.timingSafeEqual(Buffer.from(signature || ''), Buffer.from(expected))) {
return res.status(401).json({ error: 'Invalid signature' })
}
const event = JSON.parse(req.body)
// Process event here — respond first, process async for slow operations
res.json({ received: true })
}
)Python (FastAPI) Verification
import hashlib, hmac, os
from fastapi import FastAPI, Request, HTTPException
app = FastAPI()
@app.post('/webhooks/cloudflare')
async def webhook(request: Request):
secret = os.environ['CLOUDFLARE_WEBHOOK_SECRET'].encode()
raw_body = await request.body()
signature = request.headers.get('cf-webhook-auth', '')
expected = hmac.new(secret, raw_body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(signature, expected):
raise HTTPException(status_code=401, detail='Invalid signature')
payload = await request.json()
return {'received': True}Common Cloudflare Webhook Errors
| Error | Cause | Fix |
|---|---|---|
| 401 Unauthorized | Signature mismatch — body parsed before verification | Use raw body bytes for HMAC, never parsed JSON |
| Timeout | Handler takes longer than Cloudflare's timeout window | Respond with 200 immediately, process async in background |
| Duplicate events | Your handler returned non-2xx, causing retries | Deduplicate using the event ID field |
| Missing events | Wrong URL registered or endpoint returning errors | Use WebhookWhisper to confirm the exact delivery URL and response |
Forward Cloudflare Webhooks to Localhost
Use WebhookWhisper to receive Cloudflare webhook events at a public HTTPS URL and relay them to your local development server — no tunnel, no CLI install, no public server required.
- Create a WebhookWhisper endpoint and paste it into Cloudflare's webhook settings
- In the Forwarding tab, set target URL to
http://localhost:3000/webhooks/cloudflare - Every Cloudflare event appears in the inspector and hits your local handler simultaneously
- Use event replay (Pro) to re-send any captured event without triggering a new action in Cloudflare
FAQ
Do I need a Cloudflare account to test webhooks?
No. WebhookWhisper includes a one-click Cloudflare sample payload so you can fire a realistic test event and verify your handler without a Cloudflare account or triggering a real Cloudflare action.
How do I find my Cloudflare webhook secret?
The webhook signing secret is shown in Cloudflare's developer settings or webhook configuration page. Each webhook endpoint gets its own secret — do not share secrets between endpoints.
What is the Cloudflare webhook timeout?
Most providers timeout after 5–30 seconds. If your handler does slow operations (database writes, external API calls), respond with HTTP 200 immediately and process the event in a background job to avoid triggering Cloudflare's retry logic.