Skip to content
Amplifier
Console

Account

Configure a webhook to receive results via push instead of polling. When a webhook is configured, the API sends an HTTP POST to your URL when analysis completes. The webhook payload contains the job result — see Response Schema for field definitions. For when to use webhooks and implementation best practices, see Production Checklist — Webhooks.

POST /v2/account/webhook

POST/v2/account/webhook
Set the webhook URL and secret for the account. Once configured, your webhook is called when an audio analysis completes.

Request Body

API Parameters
FieldTypeRequiredDescription
urlstringRequiredHTTPS URL where webhooks are sent. Must be publicly accessible.
secret_keystringRequiredSecret used to sign webhook payloads. Store securely and use only for signature verification on your server.

Example

curl -X POST "https://api.amplifierhealth.com/v2/account/webhook" \
-H "X-Account-ID: your-account-id" \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{"url":"https://your-server.com/webhooks/amplifier","secret_key":"your-webhook-secret"}'

How webhooks work

  • Webhooks are sent asynchronously when analysis completes successfully.
  • 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 avoid timeout.

Webhook request format

Headers:

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

Payload: The body contains the completed job result: job_id, status, use_case, result (with summary, signals, audio_quality, extended_metrics). See Response Schema for field definitions.

Signature verification

To verify the webhook request came from Amplifier:

  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.

Example (Python only): HMAC verification is typically implemented on your server; below uses the Python standard library.

# Requires no additional packages — hmac and hashlib are Python standard library modules.
import hmac
import hashlib

def verify_webhook_signature(secret_key: str, payload_body: str, signature_header: str) -> bool:
    expected = hmac.new(
        secret_key.encode("utf-8"),
        payload_body.encode("utf-8"),
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

# In your webhook handler:
# payload_body = request.get_data(as_text=True)  # or request.body.decode("utf-8")
# signature = request.headers.get("X-Webhook-Signature", "")
# if verify_webhook_signature(secret_key, payload_body, signature):
#     process_job(json.loads(payload_body))

Response

FieldTypeDescription
successbooleanWhether the webhook was configured.
messagestringConfirmation message.

For implementation best practices, see Production Checklist — Webhooks.

Errors

Validation errors return 422 with a detail array. For authentication (401), rate limiting (429), and other codes, see Error Reference.

GET /v2/account/credits

GET/v2/account/credits
Check remaining credits for the account.

Response

FieldTypeDescription
creditsintegerRemaining credits for the account.

If the account has no remaining credits, analyze endpoints return 402 Payment Required. Check this endpoint before submitting jobs.

Example

curl -X GET "https://api.amplifierhealth.com/v2/account/credits" \
-H "X-Account-ID: your-account-id" \
-H "X-API-Key: your-api-key"

Errors

For 401 and other codes, see Error Reference.