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.
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
- Go to Settings, then Webhooks, and select Add webhook.
- Enter a Name and the URL of your receiver. It must use
https; private, local and cloud metadata addresses are refused. - Tick the Events you want.
- 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.
Was this article helpful?
Related articles
- Import and export your dataBring customers, companies and tickets from another help desk with a CSV file, and export tickets, customers, ratings or everything.
- Create an Injaz task from a ticketTurn a customer's problem into a task for another team in Woosool Injaz, linked both ways to the ticket.
- Roles and permissionsChoose what each agent may do and which tickets they see: admin, agent, light agent or a custom role.
Still need help?
Write to the Woosool team. Sign in with your Woosool Account and we reply by e-mail and in My requests.

