Prepare for production

Use this checklist before sending production verification traffic.

Credentials and permissions

• Call Dockt only from trusted backend code.
• Store API keys, client secrets, access tokens, and webhook secrets in a secret manager.
• Give each application and environment a separate credential.
• Keep development and automated tests in a Workspace separate from production.
• Grant only the permissions the integration uses.
• Confirm credential scope and permissions with GET /v1/auth/me during setup.
• Define a credential rotation and disablement procedure.

Request safety

• Send a stable Idempotency-Key on every supported create, upload, and invitation-resend operation.
• Use a new key for each distinct logical operation.
• Set explicit connection and response timeouts in your HTTP client.
• Parse every non-2xx response as application/problem+json.
• Log x-request-id and your own correlation ID without logging secrets or document contents.
• Retry only failures that can succeed later, with exponential backoff and jitter.

Asynchronous workflows

• Treat 201 Created and 202 Accepted according to each operation’s documented lifecycle.
• Handle every Document and Assessment status.
• Distinguish Document failed from Document invalid.
• Handle every Document result and every Assessment Decision value.
• Store the exact decision_id and assessment_input_version your product acts on.
• Re-read canonical resources before delayed or high-impact actions.
• Stop foreground polling at an application-owned deadline without inventing a Dockt result.
• Reconcile unresolved Documents and Assessments with scheduled canonical reads.

Webhooks

• Read the raw request body before parsing JSON.
• Verify the timestamp and HMAC signature before trusting an event.
• Compare signatures in constant time.
• Deduplicate side effects by X-Dockt-Event-Id.
• Accept that delivery is at least once and unordered.
• Persist or enqueue the event before returning 2xx.
• Use API polling as recovery when webhook delivery is unavailable.
• Define how you will replace a webhook endpoint and its one-time signing secret.

Documents and personal data

• Upload only through trusted backend infrastructure.
• Enforce your own file type and size checks before calling Dockt.
• Avoid placing personal data in filenames, logs, idempotency keys, or external IDs.
• Apply your retention and access-control policies to stored API responses.
• Withdraw Documents that should no longer participate in active use.
• Handle an unfamiliar supported-document classification without rejecting the complete response.

Contract updates

• Generate or validate client types against OpenAPI JSON.
• Review contract changes before updating generated clients.
• Test unknown response fields and enum handling according to your language’s compatibility model.
• Keep integration tests for authentication, uploads, polling, webhooks, and Problem Details errors.

Follow API compatibility and updates for the client update workflow. Run Test your integration before sending production traffic.