# Event types (/docs/webhooks/events) 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](/docs/webhooks.md). ## 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`. ```json title="Event webhook" { "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. ```json title="Monitor webhook" { "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`. ```json title="Billing webhook" { "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](/docs/search/everywhere.md#watches) 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](/docs/webhooks.md#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](/docs/credits.md). ## 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](/docs/notifications.md) with the reason and the way back. ## Status and batch events Status events reach a URL you subscribed on the [status page](/status). 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?](/docs/status.md#webhook-events). `batch.completed` is sent once when a [batch job](/docs/batch.md#the-completion-webhook) 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](/docs/events.md) 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. ## Next steps - [Verify a signature](/docs/webhooks/verify.md): Check that a delivery came from SocialCrawl, for each signing scheme. - [Test your webhooks](/docs/webhooks/testing.md): Send a test event and catch a real delivery on your machine. - [Events feed](/docs/events.md): Read the same events in order, with no webhook.