Webhooks integration

This document describes the various webhook types available for interaction with external systems. Webhooks are triggered by specific events in the queue system, and each webhook type corresponds to different actions or changes within the system.

Webhook Types

Each webhook type is contained in the type field of the payload sent to the destination URL. The receiving endpoint must appropriately handle the incoming POST request payload.

Webhook Type	Description

Webhook Type	Description
positionCreated	Triggered when a walk-in or manual ticket is created.
bookingConfirmation	Triggered when a customer creates a new booking.
bookingActivated	Triggered when a booking is activated (i.e., the timeslot becomes active).
bookingUpdated	Triggered when a booking is updated (e.g., rescheduled).
positionRemoved	Triggered when staff reject a ticket.
positionRetry	Triggered when staff call retry on a ticket.
positionCalled	Triggered when staff call a position.
positionFulfilled	Triggered when staff check in a position.
positionCompleted	Triggered when staff check out a position.
positionCancelled	Triggered when a customer cancels a position.
positionCancelledByStaff	Triggered when staff cancel an upcoming booking.
feedbackReceived	Triggered when a customer updates feedback on a ticket.

Webhook Payload

Webhook payloads are sent in a POST request. The request supports headers configuration, which can be used for authentication purposes.

Field	Type	Description

Field	Type	Description
message	string	Present for some webhook types; communicates a message to the customer associated with the event.
data	object	Contains detailed information about the event.

Data Fields

Field	Type	Description

Field	Type	Description
position	object	Represents the current state of the ticket or booking (Position model).
type	string	Type of the webhook, corresponding to the actions listed above.
organization	string	Name of the organization to which the queue event corresponds.

Position created webhook

{
  "message": null,
  "data": {
    "position": {
      "status": "pending",
      "priority": 0,
      "location": {
        "locationName": "Ombori Stress Test 1",
        "organizationTitle": "Ombori Title"
      },
      "label": "A2",
      "locale": "en",
      "registrationData": {
          "phone": { value: "+48888888888" },
      },
      "notification": {
        "type": "phoneNumber",
        "settings": {
          "from": "",
          "to": "+460000",
          "recipient": ""
        }
      },
      "id": "4f288ab1-72c9-402a-95b3-296766336b68",
      "type": "anonymous",
      "queue": "b23bea4f-8e8a-4da6-b413-04454f8428aa",
      "createdAt": "2021-01-21T14:05:17.527Z"
    }
  },
  "type": "positionCreated",
  "organization": "ombori"
}

Booking created webhook

{
  "message": "Your booking for 2021-01-21 15:10 is now confirmed. Ticket: https://qr.run/Pt5vJ05h",
  "data": {
    "position": {
      "location": {
        "locationName": "Ombori Stress Test 1",
        "organizationTitle": "Ombori Title"
      },
      "type": "booking",
      "priority": 100,
      "createdAt": "2021-01-21T14:07:21.598Z",
      "locale": "en",
      "registrationData": {
          "phone": { value: "+48888888888" },
      },
      "notification": {
        "type": "phoneNumber",
        "settings": {
          "from": "",
          "to": "+460000",
          "recipient": ""
        }
      },
      "numberOfPeople": 1,
      "booking": {
        "start": "2021-01-21T14:10:00.000Z",
        "end": "2021-01-21T14:15:00.000Z",
        "virtualAppointment": {
          "isEnabled": false
        }
      },
      "status": "draft",
      "label": "",
      "id": "255c8a1d-b8b6-4fb4-b6d6-4a5416203e1b",
      "queue": "b23bea4f-8e8a-4da6-b413-04454f8428aa",
      "bookingReminderAt": null
    }
  },
  "type": "bookingConfirmation",
  "organization": "ombori"
}

Booking activated webhook

{
  "message": "Your position: B1. Please come within 15 minutes to avoid cancellation of your appointment. Ticket: https://qr.run/1WPccolK",
  "data": {
    "position": {
      "location": {
        "locationName": "Ombori Stress Test 1",
        "organizationTitle": "Ombori Title"
      },
      "type": "booking",
      "priority": 100,
      "createdAt": "2021-01-21T14:08:44.038Z",
      "locale": "en",
      "registrationData": {
          "phone": { value: "+48888888888" },
      },
      "notification": {
        "type": "phoneNumber",
        "settings": {
          "from": "",
          "to": "",
          "recipient": ""
        }
      },
      "numberOfPeople": 1,
      "booking": {
        "start": "2021-01-21T14:10:00Z",
        "end": "2021-01-21T14:15:00Z",
        "virtualAppointment": {
          "isEnabled": false
        }
      },
      "status": "pending",
      "label": "B1",
      "id": "65e8eb52-7bba-4393-9a59-0b29c9251959",
      "queue": "b23bea4f-8e8a-4da6-b413-04454f8428aa",
      "bookingReminderAt": null,
      "fulfilledAt": "2021-01-21T14:10:00.479Z",
      "leaveReminderAt": null,
      "leaveAt": null
    }
  },
  "type": "bookingActivated",
  "organization": "ombori"
}

Booking updated webhook

{
  "data": {
    "position": {
      "location": {
        "locationName": "Ombori Stress Test 1",
        "organizationTitle": "Ombori Title"
      },
      "type": "booking",
      "priority": 100,
      "createdAt": "2021-01-21T14:08:44.038Z",
      "locale": "en",
      "registrationData": {
          "phone": { value: "+48888888888" },
      },
      "notification": {
        "type": "phoneNumber",
        "settings": {
          "from": "",
          "to": "",
          "recipient": ""
        }
      },
      "numberOfPeople": 1,
      "booking": {
        "start": "2021-01-21T14:10:00Z",
        "end": "2021-01-21T14:15:00Z",
        "virtualAppointment": {
          "isEnabled": false
        }
      },
      "status": "pending",
      "label": "B1",
      "id": "65e8eb52-7bba-4393-9a59-0b29c9251959",
      "queue": "b23bea4f-8e8a-4da6-b413-04454f8428aa",
      "bookingReminderAt": null,
      "fulfilledAt": "2021-01-21T14:10:00.479Z",
      "leaveReminderAt": null,
      "leaveAt": null
    }
  },
  "type": "bookingUpdated",
  "organization": "ombori"
}

Position rejected by staff webhook

{
  "message": "Position A7 was cancelled. Visit https://qr.run/1FfHJUrk if you would like to request a new position.",
  "data": {
    "position": {
      "id": "b573b730-ab6e-4314-8c8f-1ad654aeb169",
      "status": "rejected",
      "priority": 0,
      "location": {
        "locationName": "Ombori Stress Test 1",
        "organizationTitle": "Ombori Title"
      },
      "registrationData": {
          "phone": { value: "+48888888888" },
      },
      "label": "A7",
      "locale": "en",
      "type": "anonymous",
      "queue": "b23bea4f-8e8a-4da6-b413-04454f8428aa",
      "createdAt": "2021-01-21T14:11:52.436Z",
      "rejectedAt": "2021-01-21T15:05:17.527Z",
      "servedBy": {},
      "station": null
    }
  },
  "type": "positionRemoved",
  "organization": "ombori"
}

Position retry by staff webhook

{
  "message": "We called your ticket, but did not find you. We will try again in few minutes. Please approach the entrance.",
  "data": {
    "position": {
      "id": "efe8bc5d-4afc-431b-bad6-321707b08447",
      "status": "pending",
      "priority": 0,
      "location": {
        "locationName": "Ombori Stress Test 1",
        "organizationTitle": "Ombori Title"
      },
      "registrationData": {
          "phone": { value: "+48888888888" },
      },
      "label": "A4",
      "locale": "en",
      "notification": {
        "type": "applePass",
        "settings": {
          "passTypeIdentifier": "pass.com.ombori.queueservice",
          "devices": []
        }
      },
      "type": "anonymous",
      "queue": "b23bea4f-8e8a-4da6-b413-04454f8428aa",
      "createdAt": "2021-01-21T14:06:01.994Z",
      "calledAt": "2021-01-21T14:15:17.527Z",
      "servedBy": {},
      "retryCount": 1
    }
  },
  "type": "positionRetry",
  "organization": "ombori"
}

Position called by staff webhook

{
  "message": "It is your turn now.",
  "data": {
    "position": {
      "status": "notified",
      "priority": 0,
      "location": {
        "locationName": "Ombori Stress Test 1"
      },
      "registrationData": {
          "phone": { value: "+48888888888" },
      },
      "label": "A4",
      "locale": "en",
      "notification": {
        "type": "applePass",
        "settings": {
          "passTypeIdentifier": "pass.com.ombori.queueservice",
          "devices": []
        }
      },
      "id": "efe8bc5d-4afc-431b-bad6-321707b08447",
      "type": "anonymous",
      "queue": "b23bea4f-8e8a-4da6-b413-04454f8428aa",
      "createdAt": "2021-01-21T14:06:01.994Z",
      "calledAt": "2021-01-21T14:07:01.994Z",      
      "servedBy": {},
      "station": null
    }
  },
  "type": "positionCalled",
  "organization": "ombori"
}

Position checked-in by staff webhook

{
  "message": null,
  "data": {
    "position": {
      "id": "efe8bc5d-4afc-431b-bad6-321707b08447",
      "status": "fulfilled",
      "priority": 0,
      "location": {
        "locationName": "Ombori Stress Test 1",
        "organizationTitle": "Ombori Title"
      },
      "registrationData": {
          "phone": { value: "+48888888888" },
      },
      "label": "A4",
      "locale": "en",
      "notification": {
        "type": "applePass",
        "settings": {
          "passTypeIdentifier": "pass.com.ombori.queueservice",
          "devices": []
        }
      },
      "type": "anonymous",
      "queue": "b23bea4f-8e8a-4da6-b413-04454f8428aa",
      "createdAt": "2021-01-21T14:06:01.994Z",
      "servedBy": {},
      "retryCount": 1,
      "station": null,
      "calledAt": "2021-01-21T14:06:01.994Z",
      "fulfilledAt": "2021-01-21T14:07:07.074Z",
      "completedAt": "2021-01-21T15:06:01.994Z",      
      "leaveReminderAt": null,
      "leaveAt": null
    }
  },
  "type": "positionFulfilled",
  "organization": "ombori"
}

Position checked-out by staff

{
  "message": null,
  "data": {
    "position": {
      "id": "d144003e-14bb-4d17-b67d-f501c066f563",
      "status": "completed",
      "priority": 0,
      "location": {
        "locationName": "Ombori Stress Test 1",
        "organizationTitle": "Ombori Title"
      },
      "registrationData": {
          "phone": { value: "+48888888888" },
      },
      "label": "A6",
      "locale": "en",
      "type": "anonymous",
      "queue": "b23bea4f-8e8a-4da6-b413-04454f8428aa",
      "createdAt": "2021-01-21T14:11:15.694Z",
      "servedBy": {},
      "station": null,
      "fulfilledAt": "2021-01-21T14:11:21.276Z",
      "calledAt": "2021-01-21T14:25:01.994Z",
      "completedAt": "2021-01-21T15:06:01.994Z",            
      "leaveReminderAt": null,
      "leaveAt": null
    }
  },
  "type": "positionCompleted",
  "organization": "ombori"
}

Position cancelled by customer webhook

{
  "message": null,
  "data": {
    "position": {
      "id": "cce2ae86-1f5c-4dd4-b040-0b606a850f62",
      "location": {
        "locationName": "Ombori Stress Test 1",
        "organizationTitle": "Ombori Title"
      },
      "registrationData": {
          "phone": { value: "+48888888888" },
      },
      "type": "booking",
      "priority": 100,
      "createdAt": "2021-01-11T14:48:24.479Z",
      "rejectedAt": "2021-01-21T15:06:01.994Z",
      "locale": "en",
      "notification": {
        "type": "phoneNumber",
        "settings": {
          "from": "",
          "to": "+4600000000",
          "recipient": ""
        }
      },
      "numberOfPeople": 1,
      "booking": {
        "start": "2021-01-13T05:30:00Z",
        "end": "2021-01-13T06:00:00Z"
      },
      "status": "rejected",
      "label": "",
      "queue": "dd31dda9-5ec0-46c6-a75b-71cb1f66a48d",
      "QRCodeCheckInPositionId": "{\"type\":\"check-in-position\",\"positionId\":\"cce2ae86-1f5c-4dd4-b040-0b606a850f62\"}",
      "bookingReminderAt": "2021-01-13T05:00:00Z"
    }
  },
  "type": "positionCancelled",
  "organization": "ombori"
}

Booking cancelled by staff webhook

{
  "message": null,
  "data": {
    "position": {
      "id": "cce2ae86-1f5c-4dd4-b040-0b606a850f62",
      "location": {
        "locationName": "Ombori Stress Test 1",
        "organizationTitle": "Ombori Title"
      },
      "registrationData": {
          "phone": { value: "+48888888888" },
      },
      "type": "booking",
      "priority": 100,
      "createdAt": "2021-01-11T14:48:24.479Z",
      "rejectedAt": "2021-01-21T15:06:01.994Z",
      "locale": "en",
      "notification": {
        "type": "phoneNumber",
        "settings": {
          "from": "",
          "to": "+4600000000",
          "recipient": ""
        }
      },
      "numberOfPeople": 1,
      "booking": {
        "start": "2021-01-13T05:30:00Z",
        "end": "2021-01-13T06:00:00Z"
      },
      "status": "rejected",
      "label": "",
      "queue": "dd31dda9-5ec0-46c6-a75b-71cb1f66a48d",
      "QRCodeCheckInPositionId": "{\"type\":\"check-in-position\",\"positionId\":\"cce2ae86-1f5c-4dd4-b040-0b606a850f62\"}",
      "bookingReminderAt": "2021-01-13T05:00:00Z"
    }
  },
  "type": "positionCancelledByStaff",
  "organization": "ombori"
}

Feedback received webhook

{
  "data": {
    "position": {
      "id": "788ab8bd-1590-4bfb-8569-7a4920a3d679",
      "status": "completed",
      "priority": 0,
       "location": {
        "locationName": "Ombori Stress Test 1",
        "organizationTitle": "Ombori Title"
      },
      "registrationData": {
          "phone": { value: "+48888888888" },
      },
      "label": "A2",
      "locale": "en",
      "type": "booking",
      "queue": "dd31dda9-5ec0-46c6-a75b-71cb1f66a48d",
      "createdAt": "2020-12-14T12:16:20.308Z",
      "extraStatus": "goToEntrance",
      "QRCodeCheckInPositionId": "{\"type\":\"check-in-position\",\"positionId\":\"788ab8bd-1590-4bfb-8569-7a4920a3d679\"}",
      "station": {
        "id": "259a8de4-f5ea-42c4-a9af-e272a42f1b6f",
        "label": "C2"
      },
      "notification": {
        "type": "phoneNumber",
        "settings": {
          "from": "",
          "to": "+4600000000"
        }
      },
      "numberOfPeople": 1,
      "booking": {
        "start": "2020-12-14T12:30:00Z",
        "end": "2020-12-14T13:00:00Z"
      },
      "fulfilledAt": "2020-12-14T12:16:26.473Z",
      "calledAt": "2021-01-14T12:06:01.994Z",
      "leaveReminderAt": null,
      "leaveAt": null,
      "feedback": {
        "rating": 4,
        "message": "Lorem ipsum"
      }
    }
  },
  "type": "feedbackReceived",
  "organization": "ombori"
}

Ombori Apps Knowledge Base