> **For coding agents and LLMs:** This is one page from the Social Fetch docs (markdown export). For curated orientation and workflow guidance, start with [`/llms.txt`](https://www.socialfetch.dev/llms.txt); for agent onboarding and crawl rules, use [`/agents.txt`](https://www.socialfetch.dev/agents.txt); for the full endpoint list with links to pages like this one, use [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt); for one platform's parameters and curls, use [`/llms-{platform}.txt`](https://www.socialfetch.dev/llms-tiktok.txt); use [`/llms.json`](https://www.socialfetch.dev/llms.json) when you need structured JSON for tool registration.

## This page

- **On-site (HTML):** [https://www.socialfetch.dev/docs/monitors/testing-locally](https://www.socialfetch.dev/docs/monitors/testing-locally)
- **Markdown (.mdx) URL:** [https://www.socialfetch.dev/docs/monitors/testing-locally.mdx](https://www.socialfetch.dev/docs/monitors/testing-locally.mdx)

## API base URL and authentication

- **API origin (from OpenAPI `servers`):** `https://api.socialfetch.dev`
- **Authentication:** send `x-api-key: sfk_...` on `/v1/**` routes unless the operation is explicitly anonymous (check OpenAPI `security`, the [API reference hub](https://www.socialfetch.dev/docs/api.mdx), [`/llms.txt`](https://www.socialfetch.dev/llms.txt), or [`/llms.json`](https://www.socialfetch.dev/llms.json) for each route).
- **OpenAPI JSON:** [https://www.socialfetch.dev/openapi.json](https://www.socialfetch.dev/openapi.json)

## Recommended docs entrypoints (this site)

- [Documentation overview](https://www.socialfetch.dev/docs.mdx) — top-level orientation (markdown).
- [Quickstart](https://www.socialfetch.dev/docs/quickstart.mdx) — authenticate with `x-api-key`, validate auth with `whoami`, and understand the JSON envelope.
- [SDK](https://www.socialfetch.dev/docs/sdk.mdx) — official TypeScript SDK guide, including `SocialFetchClient`, `Result`, and `unwrap()`.
- [SDK reference](https://www.socialfetch.dev/docs/sdk-reference.mdx) — exhaustive SDK method inventory and route mapping for agents, tooling, and power users.
- [Choose the right endpoint](https://www.socialfetch.dev/docs/choose-endpoint.mdx) — task-oriented route selection for smoke tests, profiles, list endpoints, and single-item lookups.
- [Capability matrix](https://www.socialfetch.dev/docs/capability-matrix.mdx) — fast comparison of identifiers, pagination, outcomes, media download, and SDK coverage.
- [Recipes](https://www.socialfetch.dev/docs/recipes.mdx) — copyable workflows (brand monitoring, transcripts, Ad Library, creator scoring, Reddit research) with credit callouts and SDK examples.
- [Integrations](https://www.socialfetch.dev/docs/integrations.mdx) — MCP for AI clients, n8n verified node, Apify Store Actors, SDK, and REST API connection paths.
- [MCP product page](https://www.socialfetch.dev/mcp) — hosted MCP overview, OAuth, Skills install.
- [MCP integration](https://www.socialfetch.dev/docs/integrations/mcp.mdx) — hosted `/mcp` server, OAuth, Cursor/VS Code/Claude install snippets, 162 endpoint tools, plus docs_search/docs_read for implementation help.
- [n8n integration](https://www.socialfetch.dev/docs/integrations/n8n.mdx) — install `n8n-nodes-socialfetch`, credentials, and workflow examples.
- [Apify integration](https://www.socialfetch.dev/docs/integrations/apify.mdx) — Store Actors under @social-fetch, PPE billing, dataset export, and quick start.
- [`/llms-endpoints.txt`](https://www.socialfetch.dev/llms-endpoints.txt) — every documented operation with a direct link to that route's agent-readable markdown page (prefer this over parsing OpenAPI).
- [`/llms-{platform}.txt`](https://www.socialfetch.dev/llms-tiktok.txt) — per-platform endpoint files generated from OpenAPI (parameters, credits, curls).
- [`/agents.txt`](https://www.socialfetch.dev/agents.txt) — agent crawl/onboarding file with capabilities, auth rules, and allowlist.
- [`/llms.json`](https://www.socialfetch.dev/llms.json) — structured machine-readable operation inventory with parameter names, pagination, outcomes, credits, and SDK mapping.
- [API reference hub](https://www.socialfetch.dev/docs/api.mdx) — human-friendly index of operations with links into generated pages.
- [Errors](https://www.socialfetch.dev/docs/errors.mdx) — shared error envelope and HTTP status guidance.
- [Credits](https://www.socialfetch.dev/docs/credits.mdx) — metering, `402`, and planning batch jobs.
- Outcome semantics such as `found`, `not_found`, and `private` are documented in [Errors](https://www.socialfetch.dev/docs/errors.mdx) and on operation pages when present in the OpenAPI contract.

## Markdown docs convention

- Every docs page has a markdown twin: append **`.mdx`** to the docs pathname (for example `/docs/quickstart` → `/docs/quickstart.mdx`).
- Agents that send `Accept: text/markdown` on `/docs/**` HTML URLs may receive markdown directly (same URL, `Vary: Accept`).

---
# Testing webhooks locally (https://www.socialfetch.dev/docs/monitors/testing-locally)

You don't need a public URL to develop against webhooks. Use a hosted test inbox to inspect deliveries, or `socialfetch listen` to forward signed events to `localhost`.

## Test inbox (sink endpoints)

A **sink** is a webhook endpoint with no URL. Monitors attach to it like a real endpoint — deliveries are signed and logged — but the signed request (headers + raw body) is captured instead of POSTed. The dashboard shows it as a live inbox: deliveries appear within seconds, each expandable to the full signed request.

The response includes a one-time `secret` — store it; it's shown only once. Read captured deliveries with:

Each delivery's `requestHeaders` and `payloadText` are byte-identical to what a real HTTP endpoint would receive. Verify them the same way as production (see [Receiving & verifying webhooks](/docs/monitors/webhooks)).

Limits: **2 sinks per account**, 30-day retention. In the monitor creation wizard, "test inbox" creates one for you.

## `socialfetch listen` — forward events to localhost

Shipped in `@socialfetch/sdk`, modeled on `stripe listen`. It finds or creates a sink, polls deliveries, and forwards each one byte-exact to a local URL — original raw body, original `socialfetch-*` headers, real signature. Your local handler verifies it the same way as production.

```bash
npx socialfetch listen --forward-to http://localhost:3000/api/webhooks/socialfetch
```

```
socialfetch listen
Forwarding to http://localhost:3000/api/webhooks/socialfetch
Created test inbox whe_01J9example
Signing secret (shown once — store it now): sfwh_...
Waiting for events... (Ctrl+C to stop)
→ twitter.profile.tweets.new_items [evt_01J9…] ✓ 200 OK (43ms)
```

Flags:

| Flag                      | Required | Description                                        |
| ------------------------- | -------- | -------------------------------------------------- |
| `--forward-to <url>`      | yes      | Local URL to forward events to.                    |
| `--api-key <key>`         | no       | Defaults to `SOCIALFETCH_API_KEY`.                 |
| `--api-url <url>`         | no       | Override the API origin. Defaults to production.   |
| `--poll-interval-ms <ms>` | no       | Poll interval in milliseconds. Defaults to `2000`. |
| `-h`, `--help`            | no       | Show usage.                                        |

What it does:

1. Authenticates with `SOCIALFETCH_API_KEY` (env or `--api-key`).
2. Finds or creates a sink described `cli-listen` and reuses it on later runs. The secret is only printed on first create; rotate it if you've lost it.
3. Short-polls `GET /v1/webhook-endpoints/{id}/deliveries?after={cursor}` every 2 seconds by default. Free management call.
4. Forwards each new delivery to `--forward-to`, unmodified.
5. Prints event type, event id, and local response status/latency (or the local error).

No websockets or tunnels — a thin loop over the same APIs on this page.

## Trigger a check on demand

`POST /v1/monitors/{id}/trigger` runs a check immediately:

```json
{ "data": { "triggered": true } }
```

Triggering is free; the poll it enqueues bills at the operation's normal per-check price. See [Billing for monitors](/docs/monitors/billing). Rate-limited to once per 60 seconds per monitor.

## The full local dev loop

Terminal 1:

```bash
npx socialfetch listen --forward-to http://localhost:3000/api/webhooks/socialfetch
```

Terminal 2:

If the target has anything new since the last check, an event fires, lands in the CLI's sink, and is forwarded to your local server within seconds.

  If you don't want to wait on real content changing, `POST /v1/webhook-endpoints/{id}/test` sends a sample event shaped from that source's schema (pass `{ "sampleType": "twitter.profile.tweets.new_items" }` for a source-specific shape, or omit it for a generic one) and returns the delivery result inline. Works against a sink or a real endpoint. `socialfetch listen` forwards test events the same as real ones.

## Where to go next

- [Receiving & verifying webhooks](/docs/monitors/webhooks) — Next.js, Hono, and Express handlers, plus the raw-body gotcha.

- [Delivery, retries & idempotency](/docs/monitors/delivery-retries) — Retry schedule, at-least-once delivery, and dedup guidance.

- [Billing for monitors](/docs/monitors/billing) — Per-check credits, dryRun previews, and plan limits.

- [Webhook endpoints API reference](/docs/api/v1/webhook-endpoints/post) — Schemas for endpoints, deliveries, tests, and redelivery.