Webhooks

Receive real-time notifications when events occur in your Auralytik account. Register an endpoint, choose the events you care about, and we will POST a signed JSON payload to your server every time an event fires.

Endpoints

Method	Path	Scope	Description
GET	/api/v1/webhooks	webhooks:manage	List all webhook registrations
POST	/api/v1/webhooks	webhooks:manage	Create a new webhook (returns signing secret)
PATCH	/api/v1/webhooks/{id}	webhooks:manage	Update URL, events, or active status
DELETE	/api/v1/webhooks/{id}	webhooks:manage	Delete / deactivate a webhook
POST	/api/v1/webhooks/{id}/test	webhooks:manage	Send a test event to the webhook
GET	/api/v1/webhooks/{id}/deliveries	webhooks:manage	View delivery history and statuses

Event Types

Event	Description
evaluation.completed	Evaluation finished AI processing
audio.transcribed	Audio transcription complete
audio.processed	Audio fully processed (transcription + evaluation)
voice-call.completed	Voice bot call ended
export.ready	Analytics export ready for download
usage.quota_warning	Usage reached 80% of quota
api-key.rotated	API key was rotated

Create a Webhook

curl -X POST https://api.auralytik.ai/api/v1/webhooks \
  -H "X-Api-Key: ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/auralytik",
    "events": ["evaluation.completed", "audio.processed"],
    "description": "Production webhook"
  }'

Response:

{
  "id": "wh_8f3a1b2c",
  "url": "https://your-server.com/webhooks/auralytik",
  "events": ["evaluation.completed", "audio.processed"],
  "description": "Production webhook",
  "active": true,
  "signing_secret": "whsec_k7G2...xQ9",
  "created_at": "2026-03-30T14:22:00Z"
}

Store the signing_secret securely -- it is only returned once at creation time.

Payload Example

Every delivery is an HTTP POST with a JSON body. The outer envelope is the same for all event types; the data object varies per event.

{
  "id": "evt_9d4e2f1a",
  "event": "evaluation.completed",
  "timestamp": "2026-03-30T14:25:00Z",
  "data": {
    "evaluation_id": "eval_abc123",
    "engagement_id": "eng_xyz789",
    "campaign": "Customer Support Q1",
    "score": 87,
    "channel": "voice",
    "duration_seconds": 245
  }
}

Signature Verification

Every webhook delivery includes an X-Webhook-Signature header. Always verify this signature before processing the payload to ensure the request originated from Auralytik and has not been tampered with.

Read the raw request body (do not parse it first).
Compute HMAC-SHA256(signing_secret, raw_body) and hex-encode the result.
Compare the computed value with the X-Webhook-Signature header using a constant-time comparison function to prevent timing attacks.
Reject the request with a 401 status if the signatures do not match.

// 1. Extract signature from header
signature = request.headers["X-Webhook-Signature"]

// 2. Compute expected signature
expected = HMAC_SHA256(signing_secret, request.raw_body)

// 3. Compare using constant-time comparison
if not constant_time_equal(expected, signature):
    return 401  // Reject the request

// 4. Process the event
process(request.body)

Retry Policy

A delivery is considered successful when your server responds with a 2xx status code within the timeout window. If a delivery fails, we retry with exponential back-off:

Attempt	Delay	Timeout
1	Immediate	10 s
2	1 minute	10 s
3	5 minutes	10 s

Automatic deactivation: If a webhook fails every delivery for 7 consecutive days, it will be automatically deactivated. You can re-enable it at any time via the API or dashboard.

Ready to get started?

Generate an API key with the webhooks:manage scope and register your first endpoint.

Request API Access