Webhooks

EOS calls your server when something happens: an order is paid, a refund goes through, a guest is let in. Signed, so you know it came from EOS.

How they work

  1. 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.
  2. Keep the secret from the answer. It is shown when the endpoint is made and when its secret is rolled, never otherwise.
  3. When one of its events happens, EOS sends a POST with a JSON body to the address, signed with the secret.
  4. Check the signature, answer 2xx within 10 seconds, then do the work.
Add an endpoint
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.

TypeWhendata.object
order.createdAn order was placed (in the shop, through the API or issued in EOS): paid, free, or waiting for payment.order
order.paidAn order's payment arrived: by card through Stripe, marked paid, or a free order.order
order.payment_failedA card payment for an order failed. The order still waits; the buyer may try again. Carries payment_error.order
order.cancelledAn order was cancelled (by staff, through the API, or left unpaid) and its tickets went back on sale.order
order.refundedMoney was refunded on an order through Stripe, in full or in part.order
checkout.session.completedA checkout session's order was placed (API checkout).checkout_session
checkout.session.expiredA checkout session's hold ended before the order was placed; its tickets went back on sale.checkout_session
checkout.session.cancelledA checkout session was cancelled and its tickets went back on sale.checkout_session
attendee.checked_inA ticket was admitted at the door, by any scanner: the EOS scanner, the API, or a check-in by hand.check in
attendee.checked_outA guest was scanned out.check in
attendee.updatedA ticket holder's name or email changed, in EOS or through the API.attendee
event.createdAn event was made in EOS (it is not on sale until published).event
event.updatedAn event's details or ticket types changed.event
event.publishedAn event went on sale.event
event.unpublishedAn event was taken off sale.event
event.cancelledAn event was cancelled.event
discount_code.createdA discount code was created, in EOS or through the API.discount code
discount_code.deletedA discount code was removed from every event it was on.discount code
enquiry.createdA message came in: through the shop's contact form or the API. It is a customer case in EOS.enquiry
pingA 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.

POST body
{
  "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"
    }
  }
}
HeaderMeaning
webhook-idThe delivery’s id. The same on every retry of one delivery: use it to ignore repeats.
webhook-timestampWhen it was sent, in seconds since 1 January 1970 (UTC).
webhook-signaturev1, then the signature, in base64. There may be several, separated by spaces.
User-AgentAVEO-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 2xx status 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-id to skip repeats, and created_at or 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 ping at 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
curl -X POST "https://eos.aveoevents.com/api/v1/webhook-endpoints/7/roll-secret" \
  -H "Authorization: Bearer $EOS_API_KEY"