How they work
- Add an endpoint: an https address on your server, and the events it wants. Use POST /webhook-endpoints with a key that has the Manage webhook endpoints permission.
- Keep the
secretfrom the answer. It is shown when the endpoint is made and when its secret is rolled, never otherwise. - When one of its events happens, EOS sends a
POSTwith a JSON body to the address, signed with the secret. - Check the signature, answer
2xxwithin 10 seconds, then do the work.
curl -X POST "https://eos.aveoevents.com/api/v1/webhook-endpoints" \
-H "Authorization: Bearer $EOS_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{"url":"https://example.com/hooks/eos","description":"Orders into our CRM","events":["order.paid","order.refunded"]}'Events
Events fire whatever caused the change: your site through the API, your team in the console, a buyer in the shop, a steward at the door, or Stripe. Leave events out, or send [], to receive every type. New types may be added: ignore any you do not handle, and still answer 2xx. Each one, with its object, is in the webhook events reference.
| Type | When | data.object |
|---|---|---|
order.created | An order was placed (in the shop, through the API or issued in EOS): paid, free, or waiting for payment. | order |
order.paid | An order's payment arrived: by card through Stripe, marked paid, or a free order. | order |
order.payment_failed | A card payment for an order failed. The order still waits; the buyer may try again. Carries payment_error. | order |
order.cancelled | An order was cancelled (by staff, through the API, or left unpaid) and its tickets went back on sale. | order |
order.refunded | Money was refunded on an order through Stripe, in full or in part. | order |
checkout.session.completed | A checkout session's order was placed (API checkout). | checkout_session |
checkout.session.expired | A checkout session's hold ended before the order was placed; its tickets went back on sale. | checkout_session |
checkout.session.cancelled | A checkout session was cancelled and its tickets went back on sale. | checkout_session |
attendee.checked_in | A ticket was admitted at the door, by any scanner: the EOS scanner, the API, or a check-in by hand. | check in |
attendee.checked_out | A guest was scanned out. | check in |
attendee.updated | A ticket holder's name or email changed, in EOS or through the API. | attendee |
event.created | An event was made in EOS (it is not on sale until published). | event |
event.updated | An event's details or ticket types changed. | event |
event.published | An event went on sale. | event |
event.unpublished | An event was taken off sale. | event |
event.cancelled | An event was cancelled. | event |
discount_code.created | A discount code was created, in EOS or through the API. | discount code |
discount_code.deleted | A discount code was removed from every event it was on. | discount code |
enquiry.created | A message came in: through the shop's contact form or the API. It is a customer case in EOS. | enquiry |
ping | A test, sent when you test an endpoint. | ping |
The payload
Every delivery has the same envelope. data.object is the same object the API returns for that thing, so code that reads an order from the API reads one from a webhook too. livemode is false for events from the company’s sandbox.
{
"id": "evt_3f9c2a7e1b4d6c8e0a2b4c6d",
"type": "order.paid",
"api_version": "2026-11-15",
"created_at": "2026-11-20T10:15:01.000Z",
"company_id": 12,
"livemode": true,
"data": {
"object": {
"object": "order",
"id": "O-7KQ2M4X",
"status": "completed",
"payment_status": "paid",
"currency": "GBP",
"total": 50,
"buyer": { "first_name": "Sam", "last_name": "Taylor", "email": "sam@example.com" },
"...": "the whole order, as GET /orders/{id} returns it"
}
}
}| Header | Meaning |
|---|---|
webhook-id | The delivery’s id. The same on every retry of one delivery: use it to ignore repeats. |
webhook-timestamp | When it was sent, in seconds since 1 January 1970 (UTC). |
webhook-signature | v1, then the signature, in base64. There may be several, separated by spaces. |
User-Agent | AVEO-Webhooks/1.0 |
Checking signatures
Never act on a webhook you have not checked: anyone can send a POST to your address. The signature is HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{body}, keyed with your secret (the part after whsec_, base64-decoded), and base64-encoded. This is the Standard Webhooks scheme, so its libraries for many languages work as they are.
- Use the raw body exactly as it arrived, before any JSON parsing.
- Compare signatures in constant time, as below.
- Refuse timestamps more than five minutes from now, so an old delivery cannot be replayed.
import express from "express";
import { Webhook } from "standardwebhooks"; // npm install standardwebhooks
const wh = new Webhook(process.env.EOS_WEBHOOK_SECRET); // whsec_...
const app = express();
// the raw body: the signature is over the exact bytes EOS sent
app.post("/hooks/eos", express.raw({ type: "application/json" }), async (req, res) => {
let event;
try {
event = wh.verify(req.body, req.headers); // checks the signature and that it is under 5 minutes old
} catch {
return res.status(400).send("bad signature");
}
if (await alreadySeen(event.id)) return res.sendStatus(200); // deliveries can repeat
switch (event.type) {
case "order.paid":
await addToCrm(event.data.object);
break;
case "order.refunded":
await markRefunded(event.data.object.id);
break;
}
res.sendStatus(200); // answer within 10 seconds; do slow work afterwards
});Answering and retries
- Answer with any
2xxstatus within 10 seconds. Anything else, a redirect, a timeout or no answer counts as failed. - EOS only connects to addresses on the public internet, checked again at the moment of connecting, and never follows redirects.
- A failed delivery is tried again after 15 seconds, then 30 seconds, 1, 2, 4, 8, 16 and 32 minutes, then hourly: 12 tries over about four hours.
- Deliveries can arrive more than once and, now and then, out of order. Use
webhook-idto skip repeats, andcreated_ator the object itself to keep the latest state. - If your server was down for longer, read what you missed from the API, such as GET /orders.
Testing and watching
- Send a test event: EOS sends a
pingat once and answers with the delivery, so you can check your endpoint from your own code. - List deliveries shows what was sent, the tries, and the last error; retry one to send it again now.
- In EOS, the API keys page and Integrations show each endpoint and its last answer.
- Build against your sandbox: its webhooks are real deliveries, marked
"livemode": false. - To reach a server on your own computer while you build, use a tunnel that gives it a public https address. Addresses on private networks are refused.
Secrets
Each endpoint has its own secret. Roll it if it may have been seen: the new one works at once and the old one stops. Keep it with your API keys, in your server’s environment.
curl -X POST "https://eos.aveoevents.com/api/v1/webhook-endpoints/7/roll-secret" \
-H "Authorization: Bearer $EOS_API_KEY"