Webhooks

Docpier POSTs to your HTTPS URL when async work finishes. You do not POST to Docpier for this. Return 2xx immediately, then process. Delivery is at-least-once — persist webhookId.

Route on product, then event. Per-item results are on GET, not in this envelope.

Envelope

Docpier sends JSON. Comments below are documentation only — they are not on the wire.

{
  "product": "docmind",              // "docmind" | "docbooks"
  "event": "PROCESSING_FINALISED",   // uppercase snake_case — see tables
  "occurred": "2026-08-15T16:02:11.000Z", // ISO 8601
  "webhookId": "01J7QK3N8X4M2P9C7R1T",   // ULID per attempt — dedupe key
  "retryCount": 0,                   // 0 on first try
  "workspaceId": "01HWORKSPACE0000000001", // that product's workspace
  "documentId": "01HDOCUMENT00000000001",  // Docmind extract jobs
  "extRef": "INV-1042",              // your id, if you sent one
  "filename": "invoice.pdf",
  "status": "COMPLETED",
  "message": null                    // optional human text on failure
}

Docbooks booking events use the same envelope with booking identifiers (bookingJobId, Docbooks workspaceId) instead of documentId. Field names follow the Docbooks domain contract — Docbooks OpenAPI.

Docmind events

Event	Your next call
PROCESSING_FINALISED	GET the document
PROCESSING_FAILED	Domain failure — do not retry the extract blindly
PROCESSING_CANCELED	None — you deleted the document while it ran
FEEDBACK_RECEIVED	Optional; HTTP 200 already had per-item status

Split: webhook on the parent only.

PROCESSING_CANCELED carries status: "FAILED", so code that branches only on status treats it as a failure. Route on event to tell a deletion apart from a failure.

Docbooks events

Event	Your next call
BOOKING_FINALISED	GET the booking job
ONBOARDING_FINALISED	GET the onboarding job
OFFBOARDING_FINALISED	GET the offboarding job

BOOKING_FINALISED fires on every terminal outcome, not just the happy one — the status on the envelope is COMPLETED, REVIEW_REQUIRED, or FAILED. Branch on it after you GET; REVIEW_REQUIRED still has a booking to show, FAILED does not. Onboarding and offboarding jobs finish COMPLETED, COMPLETED_WITH_ERRORS, or FAILED, with per-item detail on the GET.

Split booking: parent job only.

Delivery

30 s timeout per attempt. 5xx, timeouts and connection errors are retried with exponential backoff: Docmind for up to 72 hours, Docbooks up to 10 attempts within 25 hours. A 4xx response, 401 and 403 included, is not retried. Docmind delivers each event to every webhook URL configured for the workspace. Production HTTPS (TLS 1.2+). Do not 4xx for application errors you cannot fix with a retry — acknowledge, then reconcile via GET.

Auth on your URL (configured by Docpier): none (dev), Basic, Bearer, or a static API key sent in the header you name, such as X-API-Key: <key> or Authorization: Bearer <key> (Docmind). Email support@docpier.com with URL, scheme, and workspace or partner id.