Developers

Webhooks

Receive a callback when a document finishes processing instead of polling.

Register an endpoint

Create an endpoint with the API. The signing secret is shown once — store it safely.

curl -X POST https://api.mahadocr.com/v1/v2/webhooks \
  -H "Authorization: Bearer mk_live_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://your-app.example.com/hooks/mahad-ocr","events":["job.finished","review.required","input.rescan_required"]}'

Events

job.finished — every finished job (sent beside the specific event below)
review.required — a person must check one or more fields before the result is used
input.rescan_required — the capture must be retaken (blur, glare, cut-off page)
job.completed / job.failed / job.reviewed — the specific outcome
job.action_required — older name sent together with review.required, kept for existing integrations

{
  "id": "evt_…",
  "event": "review.required",
  "data": { "job_id": "…", "entity_id": "…", "decision_id": "…",
            "status": "action_required", "code": "REVIEW_FIELDS", "state_version": 1 },
  "created": "2026-09-30T10:00:00+00:00"
}

Verify the signature

Every call carries X-Mahad-Signature: t=<unix>,v1=<hex>, where v1 is the HMAC-SHA256 of "<t>.<raw body>" with your endpoint secret. Reject old timestamps to stop replays. Failed deliveries are retried with back-off; see GET /v2/webhooks/{id}/deliveries.