Purepage webhook docs

Connect Purepage results to Slack, ticketing, queues, or your own runtime without polling.

Configure webhook endpoints per workspace, subscribe them to the operational events you care about, and let Purepage push signed payloads when runs or batches finish. The same worker that processes background runs also manages retries and delivery audit history.

Current events

run.completed, run.failed, batch.completed

Security

HMAC SHA-256 signature over the raw request body.

Audit trail

Pending, retrying, delivered, and dead-letter delivery history.

Purepage webhooks are durable deliveries, not fire-and-forget callbacks.

Purepage stores each delivery attempt, signs every payload, retries transient failures with backoff, and moves exhausted deliveries into a dead-letter state you can inspect from the dashboard or API.

1. Endpoint registration

Create the endpoint with `POST /api/webhooks`, choose the subscribed events, and store the secret only in your receiving system.

2. Event enqueue

When a run or batch reaches a terminal state, Purepage creates durable webhook delivery records before any outbound HTTP request is attempted.

3. Signed delivery

The worker sends JSON to your URL with the delivery id, event type, and HMAC signature headers so your receiver can authenticate the request.

4. Retry and audit trail

Transient failures retry with backoff. Every attempt records timestamps, status codes, and the last error so you can inspect the exact failure path.

Subscribe to the run and batch milestones your systems need to react to.

Webhook endpoints subscribe per workspace. Today Purepage emits run and batch completion events, with payloads versioned so downstream consumers can parse them safely.

run.completed

Sent once a single extraction finishes successfully.

run.failed

Sent once a single extraction reaches a terminal failure.

batch.completed

Sent after a batch finishes and aggregate counts are final.

diff.created

Reserved for follow-on drift/diff workflows once diff webhooks are enabled.

Verify every request before you trust it.

Each webhook includes an HMAC SHA-256 signature in `X-Purepage-Signature-256`. Recompute the HMAC over the exact raw request body using your webhook secret, then compare in constant time.

Header	Meaning
X-Purepage-Event	Event type such as `run.completed` or `batch.completed`.
X-Purepage-Delivery	Stable delivery id for dedupe, logging, and support.
X-Purepage-Signature-256	HMAC SHA-256 of the raw request body using your webhook secret.

Sample run.completed payload

json

{
  "version": "2026-03-10",
  "type": "run.completed",
  "occurredAt": "2026-03-10T01:05:00.000Z",
  "data": {
    "run": {
      "id": "run_123",
      "url": "https://example.com/pricing",
      "status": "completed",
      "scheduleId": "schedule_456",
      "batchId": null,
      "schemaId": "schema_abc",
      "schemaVersionId": "schema_abc_v4",
      "finalUrl": "https://example.com/pricing",
      "httpStatus": 200,
      "contentType": "text/html; charset=utf-8",
      "error": null,
      "result": {
        "title": "Pricing"
      },
      "createdAt": "2026-03-10T01:04:11.000Z",
      "updatedAt": "2026-03-10T01:05:00.000Z"
    }
  }
}

Recover from transient failures without losing the event trail.

Non-2xx responses and network errors are retried automatically. Deliveries move through `pending`, `retrying`, and `dead_letter` states, with response metadata recorded for each attempt.

pending

Queued and waiting for the first send attempt.

processing

Currently being delivered by the worker.

retrying

A previous attempt failed and another attempt is scheduled.

dead_letter

Retries are exhausted or the endpoint is disabled/missing.

Retry policy

Purepage retries on network failures and non-2xx responses. Delivery history records the response status, last error, and next scheduled attempt. Once max attempts are exhausted, the delivery moves into dead_letter for manual inspection.

Expect stable, versioned JSON with enough context to route work.

Payloads include the event type, occurrence time, and the run or batch details your downstream worker needs to branch on status, schema version, source URL, or originating schedule.

run.completed payload

json

{
  "version": "2026-03-10",
  "type": "run.completed",
  "occurredAt": "2026-03-10T01:05:00.000Z",
  "data": {
    "run": {
      "id": "run_123",
      "url": "https://example.com/pricing",
      "status": "completed",
      "scheduleId": "schedule_456",
      "batchId": null,
      "schemaId": "schema_abc",
      "schemaVersionId": "schema_abc_v4",
      "finalUrl": "https://example.com/pricing",
      "httpStatus": 200,
      "contentType": "text/html; charset=utf-8",
      "error": null,
      "result": {
        "title": "Pricing"
      },
      "createdAt": "2026-03-10T01:04:11.000Z",
      "updatedAt": "2026-03-10T01:05:00.000Z"
    }
  }
}

batch.completed payload

json

{
  "version": "2026-03-10",
  "type": "batch.completed",
  "occurredAt": "2026-03-10T02:00:00.000Z",
  "data": {
    "batch": {
      "id": "batch_789",
      "status": "completed",
      "scheduleId": "schedule_456",
      "schemaId": "schema_abc",
      "schemaVersionId": "schema_abc_v4",
      "totalItems": 24,
      "completedItems": 24,
      "failedItems": 0,
      "createdAt": "2026-03-10T01:52:44.000Z",
      "updatedAt": "2026-03-10T02:00:00.000Z"
    }
  }
}