Webhook basics

Signed project webhooks for terminal import outcomes.

Configure webhooks at the project level so your application can learn when an import completes or reaches terminal failure.

Open projects

Supported events

import.completed
import.failed

Expired or otherwise failed terminal corrections use import.failed with the real final_status preserved in the payload.

Secret model

Signing secrets are generated server-side, encrypted at rest, shown exactly once on creation or rotation, and never returned in plaintext on normal dashboard reads.

Signature contract

Header: ImportFlow-Signature: t=<unix_timestamp>,v1=<hex_hmac>

Algorithm: HMAC-SHA256 over ${timestamp}.${rawRequestBody} using the project webhook secret.

Additional headers: ImportFlow-Event-Id, ImportFlow-Delivery-Id, and User-Agent: ImportFlow-Webhook/1.0.

Safe webhook payload shape

Payloads contain lifecycle facts only. No raw rows, uploaded payloads, embed tokens, customer keys, or plaintext secrets are included.

{
  "id": "78c2f2c9-8a24-47f4-bd3a-0cda2a8b5a70",
  "type": "import.completed",
  "version": "2026-04-15",
  "occurred_at": "2026-04-16T12:00:00.000Z",
  "data": {
    "project_id": "project-id",
    "import_job_id": "job-id",
    "import_kit_id": "kit-id",
    "final_status": "completed",
    "requested_rows": 42,
    "valid_rows": 40,
    "inserted_rows": 40,
    "failed_rows": 2,
    "failure_reason": null
  }
}

Retry model

Manual dashboard retry only; no automatic retry loop yet. Delivery failure never rolls back the authoritative import terminal state.

Read webhook FAQ