Skip to content

Events Reference

This page lists the events that ScrapeNest can send to your webhook endpoints.

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": "http",
    "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/api/v1/artifacts/...",
    "expires_at": "2024-01-01T12:15:05Z"
  }
}