Skip to main content
Every asynchronous operation in the Autype Developer API creates a job. You have two ways to know when it finishes:
  1. Webhooks (recommended) — receive an HTTP POST when the job completes or fails.
  2. Polling — periodically check the job status endpoint.

​
Webhooks

Add an optional webhook object to any job-creating request: 
{
  "webhook": {
    "webhookUrl": "https://your-server.com/autype-webhook",
    "webhookAuth": {
      "headerName": "X-Webhook-Secret",
      "headerValue": "your-secret-token"
    }
  }
}
FieldTypeRequiredDescription
webhookUrlstringYesURL that receives the POST notification.
webhookAuth.headerNamestringNoCustom header name for authentication.
webhookAuth.headerValuestringNoValue for the custom header.
webhookAuth.basicAuthUsernamestringNoUsername for HTTP Basic Auth.
webhookAuth.basicAuthPasswordstringNoPassword for HTTP Basic Auth.
Use either custom header auth or Basic Auth — not both. If both are provided, the custom header takes precedence.

​
Webhook payload

Autype sends a POST with Content-Type: application/json and User-Agent: Autype-Webhook/1.0. The payload structure depends on the job type: Render job (completed): 
{
  "event": "job.completed",
  "jobType": "render",
  "jobId": "a1b2c3d4-...",
  "status": "COMPLETED",
  "filename": "document.pdf",
  "completedAt": "2025-02-21T10:30:00.000Z"
}
Render job (failed): 
{
  "event": "job.failed",
  "jobType": "render",
  "jobId": "a1b2c3d4-...",
  "status": "FAILED",
  "error": "Render failed: invalid section",
  "completedAt": "2025-02-21T10:30:00.000Z"
}
Bulk render job (completed): 
{
  "event": "job.completed",
  "jobType": "bulk-render",
  "jobId": "b2c3d4e5-...",
  "status": "COMPLETED",
  "metadata": { "totalItems": 10, "completedItems": 10, "failedItems": 0 },
  "completedAt": "2025-02-21T10:31:00.000Z"
}
Tools job (completed): 
{
  "event": "job.completed",
  "jobType": "tools",
  "jobId": "c3d4e5f6-...",
  "status": "COMPLETED",
  "downloadUrl": "/api/v1/dev/tools/files/{fileId}/download",
  "completedAt": "2025-02-21T10:30:05.000Z"
}
downloadUrl is only present for tools jobs that produce an output file (e.g. merge, split). Jobs like pdf/metadata return results via the job status endpoint instead.

​
Delivery behavior

  • Single attempt — if your server is unreachable or returns a non-2xx status, the webhook is not retried.
  • Timeout — requests time out after 10 seconds.
  • Non-blocking — webhook delivery never delays or fails the job itself.

​
Supported endpoints

The webhook field is accepted on all job-creating endpoints: POST /render, POST /render/markdown, POST /render/document/{documentId}, POST /bulk-render, POST /bulk-render/file, and all POST /tools/pdf/* endpoints.

​
Polling

Poll the job status endpoint until the job reaches COMPLETED or FAILED.
Job typeStatus endpoint
RenderGET /render/{jobId}
Bulk renderGET /bulk-render/{bulkJobId}
ToolsGET /tools/jobs/{jobId}
Render job status response (completed): 
{
  "jobId": "d4e5f6a7-...",
  "status": "COMPLETED",
  "format": "PDF",
  "filename": "document.pdf",
  "downloadUrl": "https://api.autype.com/api/v1/dev/render/d4e5f6a7-.../download?token=...",
  "createdAt": "2025-02-21T10:29:55.000Z",
  "completedAt": "2025-02-21T10:30:02.000Z"
}
Most render and tools jobs complete within 2–5 seconds. Poll every 1–2 seconds with a maximum of ~60 attempts.