Webhook event types
Every event SocialCrawl sends, when it fires, what its body holds, and how to filter.
SocialCrawl sends webhooks for Discover runs, listeners, Monitors, billing, the status page and batch jobs. Each family has its own body and signature, so this page lists the events by family and names the channel that carries each one. To register a receiver, see the webhooks overview.
Quick reference
| Type | Family | When it fires | Channel |
|---|---|---|---|
discover.completed, discover.partial, discover.paused | Discover | A background or scheduled run settles in that status | Event webhook and events feed |
discover.failed | Discover | A background or scheduled run settles failed. A run you cancel sends nothing | Event webhook and events feed |
discover.progress | Discover | A background run passes each tenth of its planned searches | Event webhook and events feed |
discover.accounts_ready | Discover | A view=accounts run has enriched and judged its accounts | Event webhook and events feed |
discover.new_rows, discover.new_accounts, discover.new_items | Discover | A scheduled run settles with new results for its view | Event webhook and events feed |
discover.run_skipped | Discover | A schedule occurrence is skipped | Event webhook and events feed |
discover.run_failed | Discover | A scheduled run fails, or three skips in a row pause the schedule | Event webhook and events feed |
mention.created, mention.deleted | Listening | A listener keeps a new post, or a kept post is suppressed | Event webhook and events feed |
stream.baseline.established, stream.coverage_gap, stream.paused, stream.resumed, stream.deleted, stream.budget.warning, stream.health | Listening | A listener's first check ends, a check misses posts, its status or health changes, or it nears its cap | Event webhook and events feed |
endpoint.disabled | Account | One of your webhook endpoints was disabled | Event webhook and events feed |
| A Monitor run (no type name) | Monitor | A Monitor run finishes ok or partial | The Monitor's own webhook_url |
credits.low, credits.exhausted | Billing | Your balance crosses the low-credit threshold, or reaches zero | Billing webhook |
payment.succeeded | Billing | A credit pack purchase is fulfilled | Billing webhook |
auto_recharge.succeeded, auto_recharge.failed, auto_recharge.cap_reached | Billing | An automatic top-up adds credits, fails, or is due after the monthly limit is used | Billing webhook |
incident.created, incident.updated, incident.resolved | Status | An incident opens, a person posts an update, or it resolves | Status subscription |
maintenance.scheduled, maintenance.started, maintenance.updated, maintenance.completed | Status | A maintenance window is announced, begins, is updated or ends | Status subscription |
subscription.verification | Status | You subscribe a URL to the status page | Status subscription |
batch.completed | Batch | A batch job with a webhook finishes | The job's webhook URL |
Payload structure
Each family wraps its data in its own body.
Event webhooks arrive as an event.batch, also when the batch holds one event. Each inner event has an id, a type, a cursor, a subject, data and links. A test send adds "test": true and a cursor of null.
{
"id": "bat_V1StGXR8Z5jdHi6BmyT",
"type": "event.batch",
"data": {
"events": [
{
"id": "evt_k3m7x2q7v4b6n5c5z6w2a2s4d3",
"type": "discover.completed",
"api_version": "2026-10-01",
"created_at": "2026-10-19T10:14:52.118Z",
"cursor": "c_...",
"subject": { "kind": "discover_run", "id": "run_8Hq2LmNp4Rt6" },
"data": { "run_id": "run_8Hq2LmNp4Rt6", "status": "completed" },
"links": { "run": "https://www.socialcrawl.dev/v1/prism/discover/runs/run_8Hq2LmNp4Rt6" }
}
]
}
}Monitor webhooks send one body per run, with no event name.
{
"monitor_id": "mon_7Qk2R9xLpV",
"run_id": "run_9Fh1Ab3Cd7",
"recipe": "tiktok/profile",
"status": "ok",
"scheduled_for": "2026-07-04T09:00:00.000Z",
"alerts_fired": [],
"result": { "...": "the recipe body for this run" },
"deltas": {}
}Billing, status and batch webhooks name the event in a top-level event field. Billing adds created, a Unix time in seconds, and data.
{
"event": "credits.low",
"created": 1700000000,
"data": { "balance": 480, "threshold": 500 }
}Discover events
Discover events carry counts and ids only, never your keywords, questions or row text. Read the rows from the absolute URLs in links, with your API key.
| Type | data |
|---|---|
discover.completed, discover.partial, discover.paused, discover.failed | run_id, status, stopped_because, counts, credits, version, schedule_id. A discover.paused for service_unavailable or capacity adds auto_resumes_left |
discover.progress | run_id, status, progress (percent, legs_finished, legs_planned), counts, credits, version |
discover.accounts_ready | run_id, accounts (kept, enriched, deferred), credits, version |
discover.new_rows, discover.new_accounts, discover.new_items | schedule_id, run_id, count, ids, more_ids, version. A universal search watch adds product: "search" and baseline |
discover.run_skipped | schedule_id, reason, previous_run_id, scheduled_for |
discover.run_failed | schedule_id, run_id, reason |
counts.legs counts the run's searches by state, and counts.rows_kept counts the rows it kept. A run that answered inside the original GET call sends no event, because you already hold its result.
Listening events
Listening events carry the post a listener found. Each post is stored with ids only and filled in when the batch is frozen, in the endpoint's format. A post suppressed after its event is never sent.
| Type | Fires when | data |
|---|---|---|
mention.created | A listener kept a new post after its first check | platform, methodology_version, mention (mention_id, evidence, first_seen_at) |
mention.deleted | A kept post was suppressed. Delete every copy you stored | mention_id, evidence_id, reason |
stream.baseline.established | A listener's first check finished on every source | lanes (platform, lane, kept, dropped) |
stream.coverage_gap | A check stopped before it reached posts it had already seen | platform, lane, slot, reason, pages_read, new_ids |
stream.paused | A listener paused or stopped | status, paused_because, resumes, resumes_at, next_step |
stream.resumed, stream.deleted | A listener resumed or was deleted | reason |
stream.budget.warning | A listener reached most of its monthly credit cap | credits_net, max_credits_per_month |
stream.health | A source or a listener changed health | kind, platform, and lane, skipped_because or group where they apply |
A comment read under a kept post is a mention.created too: its evidence.record_type is comment and evidence.parent.id is the post's evidence.id. A post text that passes the size limit is cut and marked truncated: true; read it whole from the listener's mentions (links.mentions).
Monitor events
A Monitor delivers once per finished run. The run's status decides whether anything is sent.
| Run status | Delivers? | Meaning |
|---|---|---|
ok | Yes | The call returned full coverage, and result holds its data |
partial | Yes | Some parts of the call did not return, and you were refunded for them |
failed | No | The call returned no usable data. The run is refunded |
skipped | No | Your balance could not cover the run. Nothing is charged |
With suppress_webhook_unless_alert: true, a run is sent only when at least one alert rule fired.
Each entry in alerts_fired describes one rule that matched: metric (the path it watches), op (gt, lt, gte, lte, abs_change_gt, pct_change_gt or pct_change_lt), from, to, delta and pct_change. deltas holds the change of each metric since the previous ok or partial run, and is empty on the first run. A Monitor that only keeps numbers sends a different body, described under Numbers-only Monitors.
Billing events
| Type | Fires when | data |
|---|---|---|
credits.low | A call takes your balance from above the threshold to at or below it | balance, threshold |
credits.exhausted | A call takes your balance to exactly zero | balance |
payment.succeeded | A credit pack purchase is fulfilled | credits_added, new_balance, amount_gbp, plan |
auto_recharge.succeeded | An automatic top-up added credits | credits_added, new_balance, amount_gbp, plan |
auto_recharge.failed | An automatic top-up failed | reason, action_required, decline_code, advice_code, paused, attempt, next_attempt_at |
auto_recharge.cap_reached | A top-up was due after the monthly limit was used | recharges_used, max_recharges_per_month, resets_on, balance |
credits.low and credits.exhausted never fire on the same call, because a balance that lands on zero counts as exhausted. plan is a stable name such as starter, so it is safe to branch on. How the threshold is set is on Billing and credits.
Account events
endpoint.disabled tells you one of your webhook endpoints stopped receiving. Its data holds endpoint_id, reason and last_error. The reason is gone (it answered 410), failing, key_revoked or user.
A paused Monitor or schedule is a notification, not a webhook. It appears as job.paused in your notifications with the reason and the way back.
Status and batch events
Status events reach a URL you subscribed on the status page. The event name is in the body's event field and in the x-socialcrawl-event header. Your first delivery is subscription.verification, which carries the signing secret in subscription.secret. The subscription becomes active only after you answer it with a 2xx.
| Type | Fires when |
|---|---|
incident.created | An incident opens |
incident.updated | A person posts an update on an open incident |
incident.resolved | The incident is resolved |
maintenance.scheduled | A maintenance window is announced |
maintenance.started, maintenance.updated, maintenance.completed | The window begins, is updated or ends |
The body carries page (the overall state) and incident (its name, status, impact, updates and the affected components). A full sample is on Is it down or is it me?.
batch.completed is sent once when a batch job finishes. It carries job_id, endpoint, status, a summary of the counts and credits, and results_url. It never carries the rows, so read them from results_url with your key.
Event filtering
Event webhooks take a types list when you register the endpoint. Each entry is an exact type (discover.completed), a namespace wildcard (discover.*) or *. Leave types out to receive every type, now and as new products start sending events. subject_ids narrows an endpoint to events about the runs or schedules you list.
The events feed takes the same types filter on GET /v1/events, so you can read what a webhook missed.
Monitor, billing, status and batch webhooks take no filter. A Monitor sends to its own webhook_url, and suppress_webhook_unless_alert is its only switch.
