Webhooks & Job Status

Every asynchronous operation in the Autype Developer API creates a job. You have two ways to know when it finishes:

Webhooks (recommended) — receive an HTTP POST when the job completes or fails.
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"
    }
  }
}

Field	Type	Required	Description
`webhookUrl`	`string`	Yes	URL that receives the POST notification.
`webhookAuth.headerName`	`string`	No	Custom header name for authentication.
`webhookAuth.headerValue`	`string`	No	Value for the custom header.
`webhookAuth.basicAuthUsername`	`string`	No	Username for HTTP Basic Auth.
`webhookAuth.basicAuthPassword`	`string`	No	Password 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 type	Status endpoint
Render	`GET /render/{jobId}`
Bulk render	`GET /bulk-render/{bulkJobId}`
Tools	`GET /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.

Authentication Rate Limits & Quotas

Overview

Document JSON Syntax

Tools Guides

Images

Rendering

Bulk Rendering

Projects & Documents

Tools File Management

Tools PDF Actions

Tools Document Actions

Lens (AI)

Tools Jobs

Webhooks & Job Status

Webhooks

Webhook payload

Delivery behavior

Supported endpoints

Polling

​Webhooks

​Webhook payload

​Delivery behavior

​Supported endpoints

​Polling

Webhooks

Webhook payload

Delivery behavior

Supported endpoints

Polling