Webhooks

Webhooks notify your application in real time when events occur in Aurion — such as ticket creation, status changes, or call completions.

Register a Webhook

curl -X POST "https://apps.aurionai.net/api/v1/webhooks" \
  -H "X-API-Key: ak_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/aurion",
    "events": ["ticket.created", "ticket.updated", "call.completed"],
    "secret": "whsec_xxxx"
  }'

Response (201 Created):

{
  "id": "wh_abc123",
  "url": "https://your-app.com/webhooks/aurion",
  "events": ["ticket.created", "ticket.updated", "call.completed"],
  "active": true,
  "created_at": "2026-02-20T14:30:00Z"
}

Event Types

Event	Description
`ticket.created`	A new ticket was created
`ticket.updated`	A ticket was updated (status, priority, assignment)
`ticket.closed`	A ticket was closed
`ticket.reopened`	A closed ticket was reopened
`ticket.note_added`	A note was added to a ticket
`call.started`	A voice call session started
`call.completed`	A voice call session ended
`call.escalated`	A call was escalated to a human agent
`user.created`	A new user/requester was synced

Webhook Payload

Each webhook delivery sends a POST request with a JSON body:

{
  "id": "evt_xyz789",
  "type": "ticket.created",
  "timestamp": "2026-02-20T14:30:00Z",
  "data": {
    "id": 1042,
    "subject": "VPN not connecting",
    "status": "open",
    "priority": "high"
  }
}

Signature Verification

Every webhook request includes an X-Aurion-Signature header containing an HMAC-SHA256 signature of the request body, signed with your webhook secret.

Always verify the signature before processing the event.

Python

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode("utf-8"),
        payload,
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

# In your webhook handler:
# payload = request.body (raw bytes)
# signature = request.headers["X-Aurion-Signature"]
is_valid = verify_webhook(payload, signature, "whsec_xxxx")

TypeScript

import { createHmac, timingSafeEqual } from "crypto";

function verifyWebhook(
  payload: string,
  signature: string,
  secret: string
): boolean {
  const expected = `sha256=${createHmac("sha256", secret)
    .update(payload)
    .digest("hex")}`;
  return timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your webhook handler:
// payload = req.body (raw string)
// signature = req.headers["x-aurion-signature"]
const isValid = verifyWebhook(payload, signature, "whsec_xxxx");

Retry Policy

If your endpoint returns a non-2xx status code or times out (30 seconds), Aurion retries delivery with exponential backoff:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes
4th retry	2 hours
5th retry	12 hours

After 5 failed retries, the event is marked as failed. You can view delivery logs and retry failed events from the admin dashboard under Configuration > Webhooks.

Delivery Logs

List recent deliveries for a webhook:

curl "https://apps.aurionai.net/api/v1/webhooks/wh_abc123/deliveries?limit=10" \
  -H "X-API-Key: ak_live_xxxx"

Each delivery log includes the request payload, response status, response body, and timing information.

Best Practices

Respond quickly — Return a 200 immediately, then process the event asynchronously
Handle duplicates — Use the id field to deduplicate events
Verify signatures — Always validate the HMAC signature before processing
Use HTTPS — Webhook URLs must use HTTPS in production

Webhooks

On this page