Events Reference¶

This page lists the events that ScrapeNest can send to your webhook endpoints. Endpoints subscribe to any of: job.created, job.completed, artifact.ready, schedule.run_skipped, schedule.auto_paused, schedule.change_detected, and schedule.monitor_activated.

Monitors emit schedule.* events

Monitoring events use the schedule. prefix for backward compatibility. In their payloads, schedule_id is the monitor id and schedule_name is the monitor name - they refer to the same resource you manage under /v1/monitors.

Envelope¶

Every webhook event is wrapped in a standard envelope.

{
  "event_id": "2b1f0e63-2c4b-4c40-9cb1-5d1466e9f6da",
  "event_type": "job.completed",
  "version": "1.0.0",
  "schema_ref": "schemas/webhooks/v1/job.completed.json",
  "occurred_at": "2024-01-01T12:03:10Z",
  "org_id": "b3c0b88f-...",
  "org_slug": "acme",
  "data": { ... }
}

Field	Description
`event_id`	Unique identifier for this specific event occurrence.
`event_type`	The type of event (e.g., `job.completed`).
`version`	Event schema version.
`schema_ref`	Schema reference for this event type.
`occurred_at`	Timestamp when the event happened.
`org_id`	Organization identifier for the event.
`org_slug`	Organization slug for the event.
`data`	The event-specific payload.

`job.created`¶

Fired when a job is successfully accepted and queued.

{
  "event_id": "2b1f0e63-2c4b-4c40-9cb1-5d1466e9f6da",
  "event_type": "job.created",
  "occurred_at": "2024-01-01T12:03:10Z",
  "org_id": "b3c0b88f-...",
  "org_slug": "acme",
  "data": {
    "job_id": "b3c0b88f-...",
    "job_type": "light",
    "status": "queued",
    "target_url": "https://example.com",
    "created_at": "2024-01-01T12:03:10Z"
  }
}

`job.completed`¶

Fired when a job finishes successfully.

{
  "event_id": "2b1f0e63-2c4b-4c40-9cb1-5d1466e9f6da",
  "event_type": "job.completed",
  "occurred_at": "2024-01-01T12:03:10Z",
  "org_id": "b3c0b88f-...",
  "org_slug": "acme",
  "data": {
    "job_id": "b3c0b88f-...",
    "status": "succeeded",
    "artifact_count": 1,
    "duration_ms": 1250,
    "completed_at": "2024-01-01T12:00:05Z"
  }
}

`job.completed` (failed)¶

Fired when a job fails after all retries (status is failed).

{
  "event_id": "2b1f0e63-2c4b-4c40-9cb1-5d1466e9f6da",
  "event_type": "job.completed",
  "occurred_at": "2024-01-01T12:03:10Z",
  "org_id": "b3c0b88f-...",
  "org_slug": "acme",
  "data": {
    "job_id": "b3c0b88f-...",
    "status": "failed",
    "failure_reason": "timeout",
    "duration_ms": 30000,
    "completed_at": "2024-01-01T12:00:05Z"
  }
}

`artifact.ready`¶

Fired when a specific artifact (e.g., screenshot, HTML) is uploaded and ready for download.

{
  "event_id": "2b1f0e63-2c4b-4c40-9cb1-5d1466e9f6da",
  "event_type": "artifact.ready",
  "occurred_at": "2024-01-01T12:03:10Z",
  "org_id": "b3c0b88f-...",
  "org_slug": "acme",
  "data": {
    "job_id": "b3c0b88f-...",
    "artifact_id": "9e8e64d4-...",
    "artifact_type": "screenshot",
    "byte_size": 204800,
    "content_hash": "sha256:...",
    "created_at": "2024-01-01T12:00:05Z",
    "download_url": "https://api.scrapenest.com/v1/artifacts/...",
    "expires_at": "2024-01-01T12:15:05Z"
  }
}

`schedule.run_skipped`¶

Fired when a scheduled run was intentionally not created - you were out of credits (skipped_quota) or the engine is no longer included in your plan (skipped_not_allowed). A skipped run costs nothing. Successful scheduled runs emit the normal job.created and job.completed events.

{
  "event_id": "7d2c0e1a-9b3f-4a21-8c77-0f1e2d3c4b5a",
  "event_type": "schedule.run_skipped",
  "occurred_at": "2024-01-01T13:00:00Z",
  "org_id": "b3c0b88f-...",
  "org_slug": "acme",
  "data": {
    "schedule_id": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
    "schedule_name": "hourly-homepage",
    "run_status": "skipped_quota",
    "reason": "Monthly job quota reached.",
    "fired_at": "2024-01-01T13:00:00Z"
  }
}

`schedule.auto_paused`¶

Fired when ScrapeNest automatically paused a monitor for you. The reason tells you why:

monitor_blocked - the monitor's scrapes did not deliver content for 3 consecutive runs (the target kept blocking or the scrapes failed), so it was paused to stop running checks that cannot succeed. Try a higher engine tier (stealth) or adjust the target, then resume it.
interval_too_frequent, engine_not_available, schedule_limit, monitoring_not_available - a plan downgrade left the monitor outside what your new plan permits. Re-enable it after upgrading, or edit it to fit the new plan.

{
  "event_id": "5f1a2b3c-4d5e-6f70-8a9b-0c1d2e3f4a5b",
  "event_type": "schedule.auto_paused",
  "occurred_at": "2024-01-01T14:00:00Z",
  "org_id": "b3c0b88f-...",
  "org_slug": "acme",
  "data": {
    "schedule_id": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
    "schedule_name": "every-minute-stealth",
    "reason": "monitor_blocked",
    "paused_at": "2024-01-01T14:00:00Z"
  }
}

`schedule.change_detected`¶

Fired when a monitor with change detection enabled finds that the watched page (or the selected part of it) changed since the previous run. change_ratio is the fraction of the watched content that changed (0-1). diff_download_url is a short-lived signed link to the before/after diff. Sub-threshold or debounced changes are still recorded in the change history but do not fire this event.

{
  "event_id": "9a8b7c6d-5e4f-4a3b-9c2d-1e0f2a3b4c5d",
  "event_type": "schedule.change_detected",
  "occurred_at": "2024-01-01T15:00:00Z",
  "org_id": "b3c0b88f-...",
  "org_slug": "acme",
  "data": {
    "schedule_id": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
    "schedule_name": "competitor-pricing",
    "change_id": "16bb99ce-796d-4de6-8885-01a7ac3a6f1b",
    "job_id": "0922ddfc-69b0-4306-bbb0-5fe503148593",
    "old_fingerprint": "sha256:aaa1",
    "new_fingerprint": "sha256:bbb2",
    "change_ratio": 0.25,
    "diff_download_url": "https://.../16bb99ce....diff?...",
    "detected_at": "2024-01-01T15:00:00Z"
  }
}

`schedule.monitor_activated`¶

Fired once when a monitor captures its reference version on the first evaluated run. This confirms monitoring is live - it is not a change alert. Subsequent changes fire schedule.change_detected.

{
  "event_id": "1f2e3d4c-5b6a-4978-8c6d-5e4f3a2b1c0d",
  "event_type": "schedule.monitor_activated",
  "occurred_at": "2024-01-01T13:00:00Z",
  "org_id": "b3c0b88f-...",
  "org_slug": "acme",
  "data": {
    "schedule_id": "aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee",
    "schedule_name": "competitor-pricing",
    "job_id": "0922ddfc-69b0-4306-bbb0-5fe503148593",
    "captured_at": "2024-01-01T13:00:00Z"
  }
}

Events Reference¶

Envelope¶

job.created¶

job.completed¶

job.completed (failed)¶

artifact.ready¶

schedule.run_skipped¶

schedule.auto_paused¶

schedule.change_detected¶

schedule.monitor_activated¶