Webhooks & callbacks

Rather than polling a job's status, register a webhook and the API calls you back when the job changes. A webhook is just a callback URL you set when creating the job — api2convert sends an HTTP POST to it.

Register a webhook

Set a publicly reachable callback URL on the job. Delivery is an outbound POST from our servers, so the URL must be reachable from the public internet:

{
  "input": [{ "type": "remote", "source": "https://example-files.online-convert.com/document/docx/example.docx" }],
  "conversion": [{ "category": "document", "target": "pdf" }],
  "process": true,
  "callback": "https://your-app.example.com/api2convert/webhook"
}

When it fires

• By default, the webhook fires once, when the job reaches a final status — completed or failed.
• Set notify_status: true on the job to be called on every status change instead.

Payload

The request is an HTTP POST with Content-Type: application/json. The body is the full job document — the same JSON returned by GET /v2/jobs/{id}, including status, output[] (with the download URLs) and any errors/warnings. A brand-specific User-Agent is sent (e.g. API2Convert API v2 Client (https://api.api2convert.com)). The payload is not signed — there is no HMAC or Authorization header.

Delivery, timeouts & retries

• Your endpoint has 3 seconds to respond on the first attempt (10 seconds on retries).
• Acknowledge with any 2xx. A 4xx is treated as a permanent rejection and is not retried; a 5xx or a timeout is retried up to 10 times (re-queued in the background).
• If a callback host fails repeatedly (~25 failures), it is briefly skipped (~30 seconds) to protect the delivery queue.

Handling webhooks

• Respond quickly — within the timeout — with a 2xx, then do any heavy work asynchronously.
• Make your handler idempotent, keyed on the job id: retries (and notify_status) can deliver the same job more than once.
• Read the download URLs from output[] promptly — they are valid for 24 hours.