Completion webhooks

Contact us to configure an HTTPS callback for your company. Endpoints are approved individually; provisioning is manual. You receive a private whsec_… signing secret. Keep it on your backend, separate from your API key. The operator must enable your exact hostname before delivery is available.

Webhooks report terminal job state. The initial OCR POST still waits for its result. This feature does not turn the OCR request into a durable background job or remove concurrency limits. GET and exact replay remain available for recovery.

Event

{
  "event_id": "a-unique-event-id",
  "request_id": "the-original-request-id",
  "status": "succeeded",
  "expires_at": "2026-10-01T12:00:00.000Z"
}

Status is succeeded or failed. Events contain no photographs, OCR fields, API keys or provider error payloads. Retrieve the result from /api/v3/ine/{request_id} with the owning API key before its expiration.

Verify before processing

The request includes X-INE-Event-ID, X-INE-Timestamp (Unix seconds) and X-INE-Signature (v1= followed by a hexadecimal HMAC).

1. Read the exact raw request body before JSON parsing.
2. Reject a timestamp more than five minutes from your server clock.
3. Compute HMAC-SHA256 over timestamp + "." + rawBody using the full UTF-8 signing-secret string, including whsec_. Do not base64-decode the secret.
4. Compare signatures in constant time and confirm the event header matches event_id in the body.
5. Persist event_id with a uniqueness constraint, schedule your processing, and return 2xx promptly. A duplicate should also return 2xx.

Download the Node.js verification helper. It verifies the signature and timestamp; your database still needs to handle deduplication.

Delivery and recovery

Delivery is at least once. A minute scheduler retries failed deliveries with bounded backoff, up to six total attempts and no later than result expiration. Requests time out after five seconds and redirects are not followed. A callback may arrive after you have already received the successful POST response. A persisted event may be retried after an uncertain acknowledgement; deduplicate it.

Use GET to recover a result even if your webhook endpoint is unavailable. Rotating or revoking the webhook configuration cancels pending events for the old configuration; an already in-flight request may still finish. Do not treat a webhook as proof of identity or authenticity.