SocialCrawl

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

TypeFamilyWhen it firesChannel
discover.completed, discover.partial, discover.pausedDiscoverA background or scheduled run settles in that statusEvent webhook and events feed
discover.failedDiscoverA background or scheduled run settles failed. A run you cancel sends nothingEvent webhook and events feed
discover.progressDiscoverA background run passes each tenth of its planned searchesEvent webhook and events feed
discover.accounts_readyDiscoverA view=accounts run has enriched and judged its accountsEvent webhook and events feed
discover.new_rows, discover.new_accounts, discover.new_itemsDiscoverA scheduled run settles with new results for its viewEvent webhook and events feed
discover.run_skippedDiscoverA schedule occurrence is skippedEvent webhook and events feed
discover.run_failedDiscoverA scheduled run fails, or three skips in a row pause the scheduleEvent webhook and events feed
mention.created, mention.deletedListeningA listener keeps a new post, or a kept post is suppressedEvent webhook and events feed
stream.baseline.established, stream.coverage_gap, stream.paused, stream.resumed, stream.deleted, stream.budget.warning, stream.healthListeningA listener's first check ends, a check misses posts, its status or health changes, or it nears its capEvent webhook and events feed
endpoint.disabledAccountOne of your webhook endpoints was disabledEvent webhook and events feed
A Monitor run (no type name)MonitorA Monitor run finishes ok or partialThe Monitor's own webhook_url
credits.low, credits.exhaustedBillingYour balance crosses the low-credit threshold, or reaches zeroBilling webhook
payment.succeededBillingA credit pack purchase is fulfilledBilling webhook
auto_recharge.succeeded, auto_recharge.failed, auto_recharge.cap_reachedBillingAn automatic top-up adds credits, fails, or is due after the monthly limit is usedBilling webhook
incident.created, incident.updated, incident.resolvedStatusAn incident opens, a person posts an update, or it resolvesStatus subscription
maintenance.scheduled, maintenance.started, maintenance.updated, maintenance.completedStatusA maintenance window is announced, begins, is updated or endsStatus subscription
subscription.verificationStatusYou subscribe a URL to the status pageStatus subscription
batch.completedBatchA batch job with a webhook finishesThe 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.

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.

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.

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.

Typedata
discover.completed, discover.partial, discover.paused, discover.failedrun_id, status, stopped_because, counts, credits, version, schedule_id. A discover.paused for service_unavailable or capacity adds auto_resumes_left
discover.progressrun_id, status, progress (percent, legs_finished, legs_planned), counts, credits, version
discover.accounts_readyrun_id, accounts (kept, enriched, deferred), credits, version
discover.new_rows, discover.new_accounts, discover.new_itemsschedule_id, run_id, count, ids, more_ids, version. A universal search watch adds product: "search" and baseline
discover.run_skippedschedule_id, reason, previous_run_id, scheduled_for
discover.run_failedschedule_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.

TypeFires whendata
mention.createdA listener kept a new post after its first checkplatform, methodology_version, mention (mention_id, evidence, first_seen_at)
mention.deletedA kept post was suppressed. Delete every copy you storedmention_id, evidence_id, reason
stream.baseline.establishedA listener's first check finished on every sourcelanes (platform, lane, kept, dropped)
stream.coverage_gapA check stopped before it reached posts it had already seenplatform, lane, slot, reason, pages_read, new_ids
stream.pausedA listener paused or stoppedstatus, paused_because, resumes, resumes_at, next_step
stream.resumed, stream.deletedA listener resumed or was deletedreason
stream.budget.warningA listener reached most of its monthly credit capcredits_net, max_credits_per_month
stream.healthA source or a listener changed healthkind, 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 statusDelivers?Meaning
okYesThe call returned full coverage, and result holds its data
partialYesSome parts of the call did not return, and you were refunded for them
failedNoThe call returned no usable data. The run is refunded
skippedNoYour 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

TypeFires whendata
credits.lowA call takes your balance from above the threshold to at or below itbalance, threshold
credits.exhaustedA call takes your balance to exactly zerobalance
payment.succeededA credit pack purchase is fulfilledcredits_added, new_balance, amount_gbp, plan
auto_recharge.succeededAn automatic top-up added creditscredits_added, new_balance, amount_gbp, plan
auto_recharge.failedAn automatic top-up failedreason, action_required, decline_code, advice_code, paused, attempt, next_attempt_at
auto_recharge.cap_reachedA top-up was due after the monthly limit was usedrecharges_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.

TypeFires when
incident.createdAn incident opens
incident.updatedA person posts an update on an open incident
incident.resolvedThe incident is resolved
maintenance.scheduledA maintenance window is announced
maintenance.started, maintenance.updated, maintenance.completedThe 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.

Next steps