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"
}

List Webhooks

curl "https://apps.aurionai.net/api/v1/webhooks" \
  -H "X-API-Key: ak_live_xxxx"

Response:

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

Delete a Webhook

curl -X DELETE "https://apps.aurionai.net/api/v1/webhooks/wh_abc123" \
  -H "X-API-Key: ak_live_xxxx"

Returns 204 No Content on success.

Event Types

Tickets (v1):

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

Conversations (v2):

Event	Description
`conversation.created`	A new conversation was created
`conversation.updated`	A conversation was updated
`conversation.resolved`	A conversation was resolved
`conversation.assigned`	A conversation was assigned to a team or agent
`conversation.reply`	A reply was added to a conversation

Calls:

Event	Description
`call.started`	A voice call session started
`call.completed`	A voice call session ended
`call.escalated`	A call was escalated to a human agent

CSAT:

Event	Description
`csat.sent`	A CSAT survey was sent to a customer
`csat.responded`	A customer submitted a CSAT rating

Contacts & Users:

Event	Description
`user.created`	A new user/requester was synced
`contact.created`	A new contact was created
`contact.updated`	A contact was updated

Workflows:

Event	Description
`workflow.completed`	A workflow run completed successfully
`workflow.failed`	A workflow run failed
`workflow.approval_needed`	A workflow step requires approval

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

Tickets — Ticket CRUD operations
Conversations — Omnichannel conversation management
Calls & Recordings — Voice call data and transcripts
CSAT Surveys — Customer satisfaction surveys
Automation & Workflows — Workflow webhook triggers

Required Scope

API key requires the webhooks:manage scope to create, update, and delete webhook subscriptions.

Webhooks

On this page