Expand on Firecrawl's Webhook testing and debugging

webhooks/testing.mdx

@@ -17,40 +17,92 @@ Since webhooks need to reach your server from the internet, you'll need to expos
 #### Using Cloudflare Tunnels
 
 [Cloudflare Tunnels](https://github.com/cloudflare/cloudflared/releases) provide a free way to securely expose your local development server to the internet without requiring account registration or opening firewall ports:
+1. Download cloudflared from GitHub releases or use a package manager
+2. Expose your local server, by doing:
 
 ```bash
-# Download cloudflared from GitHub releases or use a package manager
-
-# Expose your local server
 cloudflared tunnel --url localhost:3000
 
 # Example output:
 # Your quick Tunnel has been created! Visit it at (it may take some time to be reachable):
 # https://abc123.trycloudflare.com
 ```
 
-Use the provided URL in your webhook configuration:
+3. Use the provided URL in your webhook configuration:
 
 ```json
 {
   "url": "https://abc123.trycloudflare.com/webhook"
 }
 ```
 
+#### Using Beeceptor CLI for local tunneling
+
+[Beeceptor CLI](https://beeceptor.com/local-tunnel/) is a tool that lets you quickly create a free public endpoint with local tunneling support for testing webhooks. You can inspect payloads, add custom response rules, and simulate delays or errors to test real-world API behavior on webhooks.
+1. Visit https://beeceptor.com/local-tunnel/ in your browser, and download beeceptor-cli.
+2. Create a local tunnel, by doing:
+```bash
+beeceptor-cli -p 3030
+
+# Example output:
+# ? Select a Beeceptor endpoint below: (Use arrow keys)
+# ❯ Create a new endpoint (Free, no credit-card or sign-up required). 
+#   Register an existing endpoint. 
+```
+When prompted, select **"Create a new endpoint"** and hit enter.
+
+3. A unique, public HTTPS endpoint will be automatically created, and the CLI will display two key URLs:
+```bash
+[2025-10-31T11:42:14.111Z] Now tunneling requests from https://qt46d0fd07809895ecab3acda7f3.free.beeceptor.com to http://127.0.0.1:3030.
+[2025-10-31T11:42:14.111Z] Dashboard: https://app.beeceptor.com/console/qt46d0fd07809895ecab3acda7f3
+```
+The first URL, is your **webhook endpoint URL**. This is the address you'll use to receive and test webhooks, and it tunnels requests directly to your local application on port 3030.
+The second URL is your dashboard where you can inspect payloads, add custom response rules, and simulate faults for testing.
+
+4. Use the provided webhook endpoint URL in your webhook configuration:
+```json
+{
+  "url": "https://qt46d0fd07809895ecab3acda7f3.free.beeceptor.com"
+}
+```
+
+## Webhook Payload Inspection
+
+### Using Cloud-Hosted Endpoints
+
+You can inspect webhooks instantly without deploying a server or setting up local tunneling. Specialized cloud services like Webhook.site provide a zero-setup, public URL to capture and inspect all incoming HTTP request payloads, ideal for quick debugging and payload inspection.
+
+#### Using Webhook.site
+
+[Webhook.site](https://webhook.site/) provides a unique, random public URL endpoint instantly upon visiting the page, requiring no sign-ups, and enabling immediate testing. It offers a host of powerful custom actions, and is also capable of local tunneling:
+1. Visit https://webhook.site/ in your browser.
+2. Copy the auto-generated URL displayed on the page. This will be your webhook endpoint URL.
+
+**Example:**
+```bash
+https://webhook.site/e0516009-a024-402b-bdf8-4320ea903efa
+```
+
+3. Use the provided URL in your webhook configuration:
+```json
+{
+  "url": "https://webhook.site/e0516009-a024-402b-bdf8-4320ea903efa"
+}
+```
+
 ## Debugging Common Issues
 
 ### Webhooks Not Arriving
 
-1. **Check URL accessibility** – Ensure your endpoint is publicly accessible
-2. **Verify HTTPS** – Webhook URLs must use HTTPS
-3. **Check firewall settings** – Allow incoming connections to your webhook port
-4. **Review event filters** – Ensure you're subscribed to the correct event types
+1. **Check URL accessibility**: Ensure your endpoint is publicly accessible by Firecrawl.
+2. **Verify HTTPS**: Webhook URLs must use HTTPS. Firecrawl, will reject non-secure HTTP endpoints.
+3. **Check firewall settings**: Allow incoming connections to your webhook port.
+4. **Review event filters**: Ensure you're subscribed to the correct event types.
 
 ### Signature Verification Failing
 
-1. **Check the secret key** – Ensure you're using the correct secret
-
-2. **Verify raw body usage** – Make sure you're using the raw request body:
+1. **Check the secret key**: Ensure you are using the correct webhook Secret key, found in your Firecrawl account settings (under the Advanced tab)
+2. **Verify raw body usage**: Make sure you're using the raw request body, and not a parsed object:
 
 ```javascript
 // ❌ Wrong - using parsed body
@@ -68,3 +120,9 @@ app.post('/webhook', (req, res) => {
     .digest('hex');
 });
 ```
+
+3. **Ensure the hashing algorithm and encoding match**:
+   - Header Name: Firecrawl sends the signature in the `X-Firecrawl-Signature` HTTP header.
+   - Header Format: The value is prefixed with the algorithm: `sha256=<hash>`. Split from `=` to obtain the hash.
+
+4. **Ensure the encoding is valid**: The Firecrawl signature is calculated using HMAC-SHA256 and the output hash is encoded as a hexadecimal string. Ensure your comparison hash is also a hexadecimal string.