Handle Your First Webhook

Webhooks notify your backend when operational events happen outside the direct request/response flow.

Common first event

A typical first webhook is a device or QES state change:

JSON
{
  "id": "2d5c4fa0-eb20-42c8-87fa-d7a864ceb2b6",
  "event": "qes.state.changed",
  "occurredAt": "2026-04-04T10:00:00Z",
  "tenantId": "tenant-production",
  "deviceId": "2dfe92c9-dfb8-4f90-9396-3f416e14fbee",
  "qesId": "b94d08a1-cb83-4d1f-a9de-e480b752fdfd",
  "payload": {
    "state": "locked"
  }
}

Handler requirements

  • Accept POST requests.
  • Return a 2xx response after successful processing.
  • Treat event IDs as idempotency keys.
  • Store failures for internal retry or investigation.