Send events to your systems with webhooks

Notify your own server when tickets, messages, customers or ratings change, check the signature, and follow deliveries and retries.

Web
On this page
  1. Add a webhook
  2. Events
  3. Check the signature
  4. Answers, retries and the log

A webhook sends a message to your server each time something happens in the help desk, so another system can react: update a CRM, post in a channel, start a workflow. Webhooks are managed by admins.

Add a webhook

  1. Go to Settings, then Webhooks, and select Add webhook.
  2. Enter a Name and the URL of your receiver. It must use https; private, local and cloud metadata addresses are refused.
  3. Tick the Events you want.
  4. Save, then copy the Signing secret: it is not shown again.

A help desk can have up to 20 webhooks. Select Send test to deliver a ping event at once and see your server's answer.

Events

Event Sent when
ticket.created A ticket is created, from any channel
ticket.updated A ticket's fields change, with the list of changes
ticket.solved A ticket is set to solved
message.created A message is added to a ticket
customer.created A new customer is created
csat.received A customer answers the satisfaction survey

Each delivery is a POST with a JSON body:

{
  "id": "6f1c2a52-8d0e-4a7b-9f3e-2b1d7c4e9a10",
  "event": "ticket.solved",
  "created_at": "2026-11-07T09:30:00Z",
  "workspace_id": "0b6e…",
  "data": {
    "ticket": {
      "number": 42,
      "subject": "Order not delivered",
      "status": "solved",
      "priority": "normal",
      "requester": { "name": "Ana Haddad", "email": "ana@example.com" }
    }
  }
}

The headers X-Aoun-Event (the event) and X-Aoun-Delivery (this delivery) come with it. The id of the body stays the same if a delivery is sent again: use it to ignore an event you already handled.

Check the signature

Every delivery carries X-Aoun-Signature: t=<time>,v1=<signature>. The signature is the HMAC-SHA256, in hexadecimal, of the time, a dot and the raw body, with your signing secret as the key. Check it on the raw body, before parsing the JSON, compare in constant time, and refuse times older than 5 minutes.

Node.js (Express):

import crypto from 'node:crypto';
import express from 'express';

const app = express();

app.post('/aoun-webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = Object.fromEntries(
    (req.get('X-Aoun-Signature') || '').split(',').map((p) => p.split('=')),
  );
  const expected = crypto
    .createHmac('sha256', process.env.AOUN_WEBHOOK_SECRET)
    .update(`${sig.t}.`)
    .update(req.body)
    .digest('hex');
  const fresh = Math.abs(Date.now() / 1000 - Number(sig.t)) < 300;
  const valid = fresh && typeof sig.v1 === 'string' && sig.v1.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(sig.v1), Buffer.from(expected));
  if (!valid) return res.status(401).end();

  const event = JSON.parse(req.body);
  // event.event, event.data …
  res.status(204).end();
});

PHP:

$body = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_AOUN_SIGNATURE'] ?? ''), $sig);
$t = $sig['t'] ?? '';
$expected = hash_hmac('sha256', $t . '.' . $body, getenv('AOUN_WEBHOOK_SECRET'));

if (abs(time() - (int) $t) > 300 || !hash_equals($expected, $sig['v1'] ?? '')) {
    http_response_code(401);
    exit;
}

$event = json_decode($body, true);
// $event['event'], $event['data'] …
http_response_code(204);

Python (Flask):

import hashlib, hmac, os, time
from flask import Flask, abort, request

app = Flask(__name__)

@app.post("/aoun-webhook")
def aoun_webhook():
    body = request.get_data()
    header = request.headers.get("X-Aoun-Signature", "")
    sig = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    t = sig.get("t", "0")
    expected = hmac.new(
        os.environ["AOUN_WEBHOOK_SECRET"].encode(),
        t.encode() + b"." + body,
        hashlib.sha256,
    ).hexdigest()
    if not t.isdigit() or abs(time.time() - int(t)) > 300 or not hmac.compare_digest(expected, sig.get("v1", "")):
        abort(401)
    event = request.get_json()
    # event["event"], event["data"] …
    return "", 204

Answers, retries and the log

Answer with any 2xx status within 10 seconds. Otherwise Aoun tries again after 1, 5 and 30 minutes, then 2, 6 and 12 hours, before marking the delivery Failed. After 20 failed deliveries in a row the webhook is switched off; fix the receiver, then switch it on again.

Select a webhook's Deliveries to see the last 30 days: status (Delivered, Waiting to retry, Failed), attempts, your server's answer and the body sent. Send again queues any delivery once more.

New secret replaces the signing secret at once: update your receiver with the new one.