Test your integration

Test your Dockt integration in a separate Workspace before you send production worker data. A Workspace isolates credentials, configuration, Documents, Assessments, Decisions, and webhooks.

Dockt uses https://api.dockt.com for public API traffic. The API does not expose a request flag that changes an operation into test mode. Use Workspace isolation to keep test data and production data separate.

Create a test environment

Set up a Workspace used only by developers and automated tests:

1. Enable the same social compliance packages you plan to use in production.
2. Create a workspace credential with only the permissions your tests need.
3. Register a webhook endpoint owned by your test environment.
4. Use fictional or synthetic personal data that you are authorized to process.
5. Keep every test external_id and idempotency key free of personal data.

Do not run integration tests in a production Workspace. Assessments do not have a delete operation, and their immutable Decisions remain part of that Workspace’s history.

Separate parser tests from processing tests

Use two kinds of tests:

• Contract tests verify that your code handles every documented response shape and enum.
• API workflow tests verify authentication, uploads, asynchronous state changes, webhooks, and recovery against the public API.

Do not require an arbitrary uploaded file to produce one exact semantic result in every automated test. Use curated OpenAPI examples for deterministic parser tests, and use API workflow tests to verify transport and lifecycle behavior.

Extract response fixtures from OpenAPI

Download the public contract in your test setup:

curl --fail-with-body --silent --show-error \
  https://api.dockt.com/openapi.json \
  --output openapi.json

Extract a curated example, such as the accepted Document upload response:

jq '.paths["/v1/documents"].post.responses["202"].content["application/json"].example' \
  openapi.json > document-uploaded.json

Use the same approach for:

• POST /v1/assessments with response 201.
• GET /v1/documents/{documentId} with response 200.
• GET /v1/assessments/{assessmentId} with response 200.
• GET /v1/decisions/{decisionId} with response 200.
• Any documented Problem Details response.

Store the extracted examples with your tests or regenerate them in a reviewed dependency-update process. Don’t download a changing contract during every production build.

Test the first API boundary

Cover these cases in your test suite:

Case	Expected behavior
Valid workspace credential	GET /v1/auth/me returns the expected Workspace and permissions.
Missing bearer token	The API returns 401 with Problem Details.
Missing permission	The API returns 403 with Problem Details.
Empty or unsupported upload	The API returns the documented invalid-upload Problem Details response.
Same idempotency key and request	Dockt replays the successful response.
Same idempotency key with a changed body	Dockt returns an idempotency conflict.

Record x-request-id when a test fails. Do not record the credential or uploaded file content.

Test asynchronous state handling

For Documents, verify that your application:

• Stores the Document ID from the 202 Accepted response.
• Handles uploaded, processing, completed, failed, and withdrawn.
• Reads document_result only after status is completed.
• Distinguishes a processing failed status from an invalid result.
• Handles unknown future issue, Finding, and classification codes safely.

For Assessments, verify that your application:

• Renders returned input_requests from their value_type and options.
• Uses the Assessment’s requirements instead of a fixed upload checklist.
• Handles a Decision created from zero or partial evidence.
• Stores the Decision ID and assessment_input_version it used.
• Detects when a later update creates a newer Decision.

Test webhooks

Use POST /v1/webhooks/{webhookId}/test to send a signed webhook.test event. Verify that your receiver:

1. Reads the raw body before parsing JSON.
2. Rejects an invalid signature.
3. Rejects a timestamp outside the five-minute replay window.
4. Stores the event ID before applying side effects.
5. Returns 2xx after durable acceptance.
6. Treats a repeated event ID as an acknowledged duplicate.

The test event proves delivery and signature handling. It does not create a Document, Assessment, or Decision.

Test recovery

Simulate failures in your own application:

• Drop one webhook after signature verification, then recover with a canonical API read.
• Deliver the same webhook twice, then confirm that the side effect runs once.
• Deliver events in a different order, then confirm that you fetch current resource state.
• Time out an upload request, then retry with the same idempotency key and body.
• Leave a resource unresolved past your application’s deadline, then confirm that you keep it pending instead of inventing a result.

Finish by reviewing Prepare for production.