diff --git a/webhooks/testing.mdx b/webhooks/testing.mdx index cfcac2ff..5c10a3e7 100644 --- a/webhooks/testing.mdx +++ b/webhooks/testing.mdx @@ -17,11 +17,10 @@ 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: @@ -29,7 +28,7 @@ cloudflared tunnel --url localhost:3000 # https://abc123.trycloudflare.com ``` -Use the provided URL in your webhook configuration: +3. Use the provided URL in your webhook configuration: ```json { @@ -37,20 +36,73 @@ Use the provided URL in your webhook configuration: } ``` +#### 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=`. 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.