Monitoring quickstart
Create a monitor and receive a signed webhook end to end — no public URL required to start.
Poll a watchable Social Fetch source and get a signed webhook when something new appears.
Before you start
- API key: create one in API Keys. Monitors need an API key (no anonymous x402 access) so polls can run against a durable account.
- Base URL:
https://api.socialfetch.dev - Cost: create/list/update/delete for monitors and webhook endpoints is free. Only the scheduled poll bills, at that operation's normal per-request price. See Billing for monitors.
- Or use the dashboard wizard, which includes a one-click test inbox.
1. Save your API key
Put the key in an environment variable. Use .env for app code, or export it in your shell for one-off requests.
2. Discover what you can watch
GET /v1/monitors/sources lists every watchable operation, its display name, how it detects new items, and a sample event:
Pick an operationId and note minIntervalMinutes — the fastest that source will poll (currently 1 minute for every watchable source).
3. Create a test inbox (no public URL needed)
A sink endpoint has a signing secret and logged deliveries, but instead of an outbound HTTP call it captures the signed request for you to inspect:
Secret shown once
secret is only returned on creation (or explicit rotation). Store it now — you'll need it to verify deliveries.
4. Create the monitor
Point the monitor at the source, a schedule, and the sink from step 3. Add ?dryRun=true first if you only want the cost preview:
Creation runs a synchronous baseline check. It charges one poll, records what already exists so those items don't fire events, and returns a preview of what it saw.
5. Trigger a check without waiting
Triggering is free; the poll it enqueues bills the normal per-check price (rate-limited to once per 60 seconds per monitor):
If the target has posted something new since the baseline, a signed delivery lands on your sink within seconds.
6. Read the captured delivery
Each delivery includes the exact requestHeaders and payloadText that would have been POSTed to a real URL — byte-identical, so you can verify the signature the same way as in production. See Receiving & verifying webhooks.
7. Point it at your real endpoint
When your handler is ready, swap the sink for your URL. Nothing else about the monitor changes:
Where to go next
Receiving & verifying webhooks
Next.js, Hono, and Express handlers — and the raw-body gotcha that breaks signature checks.
Testing webhooks locally
socialfetch listen forwards signed events to localhost. No tunnel.
Delivery, retries & idempotency
Retry schedule, at-least-once delivery, and deduping on event id.
Billing for monitors
Per-check credits × schedule, dryRun previews, and plan limits.