Webhooks

Webhooks let Keues notify your own system every time something happens to a turn. Instead of polling the API continuously, Keues sends an HTTP request to the URL you choose at the moment the event occurs.

That lets you connect Keues with your POS, your CRM, an external screen, your analytics system or any other tool that needs to know what is happening.

Configuration

Webhooks are configured in the dashboard under Settings → Webhooks. Only users with the administrator role can see and change this section.

Field	Description
Enable webhooks	Master switch. While it is off, no request is sent even if events are selected.
Webhook URL	https://… address Keues will send POST requests to.
Key	Shared secret Keues sends in the X-Keues-Key header so you can verify the request comes from your installation.
Subscribed events	List of events you want to receive. Only the selected ones are sent.

Caution

Webhook configuration is one per installation: it applies to every location. There is no separate URL per location. If you need different destinations, use your own endpoint that receives everything and routes by the location field in the payload.

Available events

Event	When it is sent
Ticket.Created	A new ticket is created.
Ticket.Called	A counter calls a ticket.
Ticket.Attended	A ticket’s service is finished.
Ticket.Transferred	A ticket is transferred to another counter.
Ticket.Canceled	A ticket is canceled.

Select only the events you actually need. Keues does not dispatch events that are not subscribed.

Example request

Keues sends a POST to your URL with a JSON body and these headers:

POST https://your-server.com/webhook HTTP/1.1
Content-Type: application/json
X-Keues-Key: your-secret-key

Example body for Ticket.Called:

{
  "eventType": "Ticket.Called",
  "occurredAt": "2026-11-07T10:24:35.120Z",
  "data": {
    "id": "3f2b9c1e-8a4d-4c6e-9b1a-2d7f5e8c0a11",
    "code": "A-042",
    "queue": {
      "id": "b1d4e6f8-2a3c-4d5e-8f90-1a2b3c4d5e6f",
      "name": "Fish counter"
    },
    "counter": {
      "id": "c2e5f7a9-3b4d-5e6f-9012-2b3c4d5e6f70",
      "name": "Checkout 2"
    },
    "user": {
      "id": "d3f6a8b0-4c5e-6f70-8123-3c4d5e6f7081",
      "name": "Ana García",
      "externalId": "ana.garcia"
    },
    "location": {
      "id": "e4a7b9c1-5d6f-7081-9234-4d5e6f708192",
      "name": "Central Market"
    }
  }
}

Payload fields

Field	Type	Description
eventType	string	One of the events in the table above.
occurredAt	string	Date and time of the event in ISO 8601 format (UTC).
data.id	string	Internal ticket identifier.
data.code	string	Ticket code as shown to the customer (for example A-042).
data.queue	object	Ticket queue: id and name.
data.counter	object | null	Counter involved in the event: id and name. It can be null, for example when the ticket is created.
data.user	object | null	User who performed the action: id, name and externalId. It can be null if the action is not linked to a user.
data.location	object	Ticket location: id and name.

The user’s externalId field is meant to link with your own system: you can store it in Keues and use it here to identify the same person without relying on the internal identifier.

Security

Keues does not sign the body with HMAC. Security relies on the shared secret sent in the X-Keues-Key header:

1. Set a long, random key in Settings → Webhooks.
2. Configure the same key on your server.
3. Reject any request whose X-Keues-Key header does not match.

app.post('/webhook', (req, res) => {
  if (req.get('X-Keues-Key') !== process.env.KEUES_WEBHOOK_KEY) {
    return res.sendStatus(401);
  }

  const { eventType, occurredAt, data } = req.body;

  // Process the event without blocking the response.
  console.log(eventType, data.code);

  res.sendStatus(204);
});

Tip

Always use https:// for the webhook URL and keep the key in an environment variable, never in the source code.

Delivery and errors

• Keues waits a maximum of 10 seconds for your server to respond.
• A delivery counts as successful when your server responds with a 2xx status code.
• There are no automatic retries: if your server is unavailable or too slow, that notification is lost. To avoid losing events, respond quickly (2xx) and process the work in the background.
• Successful and failed deliveries are recorded in the Keues server log.

Configuration API

Besides the Settings screen, the configuration can be managed through the API. All these endpoints require the administrator role:

Method	Path	Description
GET	/api/WebhooksConfig	Gets the current configuration.
PUT	/api/WebhooksConfig	Updates url, key, events and enabled.
GET	/api/WebhooksConfig/events	Returns the list of available events.

Example PUT:

{
  "url": "https://your-server.com/webhook",
  "key": "your-secret-key",
  "events": ["Ticket.Created", "Ticket.Called"],
  "enabled": true
}

Use cases

• Sync with your POS or ERP when a turn is attended.
• Show the status on another screen outside the Keues monitor.
• Measure waiting and service times in your analytics tool.
• Alert a manager when a ticket is canceled or the wait piles up.
• Link users with your system through externalId.