Webhooks

Overview

Webhooks are set up per intent, in the dashboard's Intent Config. When a conversation completes that intent (for example, a guest has given their name and number for a Human Assistance Request), YuAskMe sends the details to every webhook URL on that intent.

• Alert staff in Slack, Teams, Messenger, or by SMS through a tool like n8n or Zapier.
• Create the booking in your property management system and return its reference.
• Send orders to your POS or kitchen display, and payments to your billing system.
• Log complaints in your help desk.

For some intents, YuAskMe also reads your response: a booking reference, a room conflict, or an error message is passed straight back to the guest. See Responding to YuAskMe.

Add a webhook

1. In the dashboard, open Intent Config and choose the intent under Available Intents, for example Human Assistance Request.
2. Under Webhooks, click Add Webhook and fill in:
   • URL: the HTTPS address to call
   • Method: POST (default) or GET
   • Bearer token (optional): sent as Authorization: Bearer <token> so your endpoint can check the call came from YuAskMe
   • Label (optional): a name for your own reference
3. Click Save. You can add several webhooks to one intent; each gets the same data.

The same screen sets the intent's Response Text, the message the guest sees (HTML allowed). For example: “Our team has been notified and will be with you shortly.”

How requests are sent

POST /hooks/yuaskme HTTP/1.1
Host: your-system.example.com
Content-Type: application/json
User-Agent: YuAskMe/1.0
Authorization: Bearer your-secret-token

{ "identifier": "la-hacienda", "uid": "…", "fullname": "Maria Santos", … }

Events and payloads

Every payload includes identifier, your workspace's identifier, so one endpoint can serve several businesses. Order events also include an event name.

Human Assistance Request

Sent when a guest asks for a person and has given their name and contact number.

{
  "identifier": "la-hacienda",
  "uid": "guest-uid-or-null",
  "fullname": "Maria Santos",
  "contact_number": "09171234567",
  "message": "Can I talk to the front desk please?"
}

Complaint

Sent once the guest has given their room number and what went wrong.

{
  "identifier": "la-hacienda",
  "uid": "guest-uid-or-null",
  "room_number": "204",
  "details": "The air conditioning isn't working",
  "message": "Room 204, the aircon is broken"
}

Reservation

Sent when a guest confirms a booking (after giving their mobile number). Your endpoint can create the booking and reply with a reference.

{
  "identifier": "la-hacienda",
  "reserve": {
    "name": "Maria Santos",
    "check_in": "2026-11-20",
    "check_out": "2026-11-22",
    "guests": 2,
    "items": [
      { "room_type": "Casita", "entity_id": "…", "units": 1, "price": 1500, "nights": 2, "subtotal": 3000 }
    ],
    "total": 3000,
    "add_ons": [],
    "mobile": "09171234567",
    "address": "",
    "confirmed": true,
    "cancelled": false
  }
}

Cancellations go to the Reservation intent's webhooks too, but only when the guest gives a booking reference (a booking your system created):

{
  "identifier": "la-hacienda",
  "booking_id": "BK-2026-00021",
  "reserve": { "items": [{ "entity_id": "…" }], "cancelled": true }
}

Order Placement order.items_placement

Sent each time a customer adds, changes, or removes items, with only what changed. Each item has an action when it isn't a plain add: set (quantity is the new total) or remove.

{
  "event": "order.items_placement",
  "table_id": "T5",
  "order_session_id": "…",
  "conversation_id": "…",
  "items": [
    { "entity_id": "…", "name": "Pork Humba", "quantity": 2, "price": 150, "notes": "", "pos_item_id": "SKU-123" },
    { "entity_id": "…", "name": "Iced Tea", "quantity": 0, "price": 50, "notes": "", "pos_item_id": null, "action": "remove" }
  ]
}

pos_item_id is your point-of-sale ID for the item, if you've linked one, and table_id comes from the QR code the customer scanned.

Order Confirm order.confirmed

{
  "event": "order.confirmed",
  "identifier": "la-hacienda-cafe",
  "cart_id": "…",
  "table_id": "T5",
  "order_session_id": "…",
  "conversation_id": "…",
  "items": [ … ],
  "total_amount": 350
}

Order Payment order.payment_confirmed

Sent when the customer asks for the bill and confirms. Same fields as Order Confirm.

{
  "event": "order.payment_confirmed",
  "identifier": "la-hacienda-cafe",
  "cart_id": "…",
  "table_id": "T5",
  "order_session_id": "…",
  "conversation_id": "…",
  "items": [ … ],
  "total_amount": 350
}

Responding to YuAskMe

Reply with any 2xx status to accept. For the intents below, what you return changes what the guest sees:

For every other intent, the response body is ignored.

Form webhooks

Forms and surveys can also call a webhook when someone completes them, with the answers keyed by each field's key:

{
  "form_id": "…",
  "form_name": "Event inquiry",
  "submission_id": "…",
  "status": "completed",
  "submitted_at": "2026-10-14T07:30:00.000Z",
  "source_channel": "web",
  "business_account_id": "…",
  "individual_user_id": "…",
  "booking_id": null,
  "submitted_by": { "id": "…", "name": "Maria Santos", "email": "maria@example.com" },
  "answers": { "event_date": "2026-12-12", "guests": "80" }
}

A payment-proof form attached to a booking sends { "booking_id": "…", "reserve": { "payment_proof_url": "https://…" } } instead. Form webhooks time out after 8 seconds.

Good practices

• Use HTTPS and set a bearer token; reject calls without it.
• Reply quickly. The guest is waiting in the chat, especially for Reservation and Order webhooks, whose responses decide what they see.
• Calls aren't retried, so if your system can be down, put a queue or a tool like n8n in front of it.
• Make your handler safe to call twice. Use order_session_id, cart_id, or booking_id to spot repeats.

Something unclear or out of date? Report a docs issue.