Testing webhooks locally

Social Fetch only delivers to public https:// addresses, so it can't reach http://localhost:3000 on your machine. You don't need a public URL to build your handler, though. A test inbox keeps every delivery for you to read in the dashboard, and socialfetch listen forwards each one from the test inbox to your local server.

Test inbox

A test inbox is a webhook endpoint with no URL. Monitors attach to it like any other endpoint, and each delivery is signed and logged in the same way, but instead of sending the request anywhere, Social Fetch keeps it. You can read every request's headers and raw body, exactly as an HTTP endpoint would have received them.

1. In the app, open Monitors, then Webhook endpoints, and click Create endpoint.
2. Choose Test inbox and click Create endpoint. The URL and description fields aren't needed.

3. Copy the signing secret from the next window, as for any endpoint. You'll need it to verify deliveries.
4. When you create a monitor, choose Existing endpoint in its destination step and pick the test inbox.

Open the test inbox from the Webhook endpoints page to see its delivery log. While the page is open it checks for new deliveries every couple of seconds, so events appear without a reload. Click Send test to put a sample event in it, and click any row to see the full signed request.

You can create a test inbox through the API too:

The response includes the secret. Store it: it's only shown once. Read the inbox's deliveries with:

Each delivery's requestHeaders and payloadText are exactly what an HTTP endpoint would have received. Verify them the same way you would in production (see Receiving & verifying webhooks).

A workspace can have up to 2 test inboxes. Creating a third fails with "At most 2 test-inbox endpoints per account."; delete one you no longer use from the ⋮ menu on the Webhook endpoints page. Deliveries are kept for 30 days, as for any endpoint.

Forward events to localhost with socialfetch listen

socialfetch listen comes with @socialfetch/sdk and works like stripe listen. It uses a test inbox, checks it for new deliveries, and sends each one to a URL on your machine, unchanged: the same raw body, the same socialfetch-* headers and the real signature. Your local handler verifies it exactly as it would in production.

It needs an API key, from SOCIALFETCH_API_KEY or --api-key:

The first run creates a test inbox described cli-listen and prints its signing secret once. Set it as your local SOCIALFETCH_WEBHOOK_SECRET:

Later runs reuse the same test inbox (Using existing test inbox whe_…) and don't print the secret again. If you've lost it, rotate the cli-listen inbox's secret on the Webhook endpoints page. The cli-listen inbox counts towards the limit of 2.

What it does:

1. Finds the test inbox described cli-listen, or creates it.
2. Every 2 seconds, asks for deliveries newer than the last one it saw (GET /v1/webhook-endpoints/{id}/deliveries?after=…). Only deliveries that arrive after it starts are forwarded. Reading deliveries is free.
3. Sends each new delivery to --forward-to, unchanged.
4. Prints the event type, event id, and your server's status and response time (or the error, if your server didn't answer).

There are no websockets or tunnels: it's a short loop over the same API calls shown above.

A forwarded event your server rejects isn't sent again: the test inbox already counts it as delivered. Fix your handler, then send another test event or redeliver the event from the inbox's log.

Run a check now

You don't have to wait for a monitor's schedule. Click Run now on the monitor's page, or call POST /v1/monitors/{id}/trigger:

The check is queued straight away. Triggering is free; the check itself costs the same as a scheduled one (see Billing for monitors). You can run a monitor's check once every 60 seconds; sooner than that, the API replies "This monitor was triggered moments ago. Try again in N seconds."

A monitor's first check only records what's already there, so it sends no event. An event is sent when a later check finds something new.

The whole loop

In one terminal, start forwarding:

In another, run a check on a monitor that's attached to the cli-listen test inbox:

If the source has anything new since the last check, an event is sent to the test inbox, and socialfetch listen forwards it to your local server a couple of seconds later.

Where to go next