> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autype.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks & Job Status

> Real-time notifications via webhooks or polling for job completion

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:

```json theme={null}
{
  "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.            |

<Info>
  Use **either** custom header auth **or** Basic Auth — not both. If both are provided, the custom header takes precedence.
</Info>

### 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):**

```json theme={null}
{
  "event": "job.completed",
  "jobType": "render",
  "jobId": "a1b2c3d4-...",
  "status": "COMPLETED",
  "filename": "document.pdf",
  "completedAt": "2025-02-21T10:30:00.000Z"
}
```

**Render job (failed):**

```json theme={null}
{
  "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):**

```json theme={null}
{
  "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):**

```json theme={null}
{
  "event": "job.completed",
  "jobType": "tools",
  "jobId": "c3d4e5f6-...",
  "status": "COMPLETED",
  "downloadUrl": "/api/v1/dev/tools/files/{fileId}/download",
  "completedAt": "2025-02-21T10:30:05.000Z"
}
```

<Note>
  `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.
</Note>

### 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):**

```json theme={null}
{
  "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"
}
```

<Tip>
  Most render and tools jobs complete within 2–5 seconds. Poll every 1–2 seconds with a maximum of \~60 attempts.
</Tip>