Webhooks

Status: on the roadmap (not yet available). Today, learn about completion by polling GET /v1/submissions/{id}. This page describes the webhook contract so you can plan for it.

When available, you'll be able to register a callback URL on your API key and we'll POST an event when a submission reaches a terminal state — so you don't have to poll.

Events

Payload

{
  "id": "evt_…",
  "type": "submission.completed",
  "created_at": "2026-06-26T20:00:00Z",
  "data": {
    "organization_id": "org_…",
    "client_id": "cli_123",
    "submission": { "id": "sub_789", "status": "completed", "...": "..." }
  }
}

On receipt, call GET /v1/submissions/{id} to fetch the current submission (including fresh output_documents download URLs).

Verifying signatures

Each delivery is signed with a per-key secret using HMAC-SHA256 over the raw request body, sent in:

X-Magnetic-Signature: t=<unix_ts>,v1=<hex_hmac>

Recompute HMAC_SHA256(secret, "<t>." + raw_body) and compare to v1 (constant-time). Reject if it doesn't match or the timestamp is too old.

Networking

• We retry non-2xx responses with exponential backoff. Make your handler idempotent (dedupe on the event id).
• Respond 2xx quickly; do heavy work asynchronously.
• If your firewall allowlists inbound sources, ask us for our static egress IP addresses — all webhook calls originate from them.