Jobs, Polling, and Webhooks

Job lifecycle, polling, and webhook delivery for completed analysis.

Analyze returns a job immediately. The result arrives later. Endpoints: Jobs API, Account API (webhooks).

Submit

Submit returns a job object right away, with job_id, status: queued, and result: null:

{
  "job_id": "189bce4a-52cb-4e60-8586-cef89e719109",
  "status": "queued",
  "created_at": "2026-02-22T09:14:00Z",
  "completed_at": null,
  "result": null,
  "job_type": "model",
  "api_version": "v2",
  "model_name": "pulse"
}

job_type is "model" or "sign". Both model_name and sign_name may be present; the unused discriminator is null. See Response Schema.

Job statuses

status moves through queued and running to one of three terminal values.

For a valid job_id on your account, GET /v2/jobs/{job_id} returns 200 OK with the job object. failed and timed-out are expressed in status in the body, not only via HTTP error codes. Poll until status is done, failed, or timed-out, then branch. Full contract: Response Schema — Job status: failed or timed-out.

When status is done, read result. Model jobs: summary, signals[], audio_quality, extended_metrics. Sign jobs: signal plus audio_quality. Fields: Response Schema. How to act: Interpreting Results.

Polling

Retrieve the job with GET /v2/jobs/{job_id}:

curl https://api.amplifierhealth.com/v2/jobs/189bce4a-52cb-4e60-8586-cef89e719109 \
  -H "X-Account-ID: your-account-id" \
  -H "X-API-Key: your-api-key"

const response = await fetch("https://api.amplifierhealth.com/v2/jobs/189bce4a-52cb-4e60-8586-cef89e719109", {
  headers: {
    "X-Account-ID": process.env.AMPLIFIER_ACCOUNT_ID,
    "X-API-Key": process.env.AMPLIFIER_API_KEY,
  },
});

const data = await response.json();

# Requires httpx: pip install httpx
import os
import httpx

response = httpx.get(
  "https://api.amplifierhealth.com/v2/jobs/189bce4a-52cb-4e60-8586-cef89e719109",
  headers={
      "X-Account-ID": os.environ["AMPLIFIER_ACCOUNT_ID"],
      "X-API-Key": os.environ["AMPLIFIER_API_KEY"],
  },
)

data = response.json()

Poll at 2–5 second intervals. Most jobs complete within a few seconds; longer recordings may take up to 30 seconds. Diarized and long recordings can take several minutes. This cadence fits within the job status polling rate limit.

Parse timestamps with an ISO 8601-compatible library — the API may return timestamps with or without fractional seconds and with varying timezone designators. See Response Schema — Timestamps.

Webhooks

Webhooks POST the job object at a terminal status. Use when the submitter cannot poll, or as an audit trail. Still poll as fallback.

Register a webhook with POST /v2/account/webhook: url (URI, max 2083 characters; HTTPS in production) and secret_key. Per-job override: webhook_url + webhook_secret_key on analyze — send the secret whenever you send a URL. Shapes: Account API.

How webhooks work

• Webhooks are sent asynchronously when the job reaches a terminal status: done, failed, or timed-out. The body is the job object — check status before reading result. Polling is still useful as a fallback, including for jobs that never reach done.
• The API sends an HTTP POST to your configured URL with a JSON payload.
• If your endpoint is unavailable or returns a non-2xx status, the system retries delivery up to 5 times with increasing delays. Respond within 30 seconds to stay inside the delivery timeout.

Webhook request format

Headers:

• Content-Type: application/json
• X-Webhook-Signature — HMAC-SHA256 signature of the raw request body; use it to verify the request came from Amplifier.

Payload: the completed job object. Check status before reading result. Fields: Response Schema.

Signature verification

Verify every payload before processing it:

1. Read the raw request body (as bytes or string) and the X-Webhook-Signature header.
2. Compute HMAC-SHA256 of the raw body using your secret_key.
3. Compare the computed value with the header using a constant-time comparison.

Keep the secret_key on your server and use it only for signature verification.

Handling retries

Because delivery is retried, the same job_id can arrive more than once. Implement an idempotency check on job_id so a repeated delivery is recognized and processed once.

Choosing polling or webhooks

Both can be used together: register a webhook and still poll as a fallback.

Error handling

401: check X-Account-ID and X-API-Key. 429: exponential backoff; read Retry-After. 500: exponential backoff. Codes: Errors.

GET /v2/jobs/{job_id} returns 404 for a missing or cross-account job_id — Errors.

When result.summary.recommended_action is inconclusive, treat it as no clear signal; prefer re-recording — Recommended action logic.