> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.kychospitality.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks overview

> Get notified when something happens at a property, instead of polling the API.

Webhooks let KYC tell your system when something happens, such as a new guest message.
KYC sends an HTTPS `POST` to your endpoint for each event you subscribe to.

Each request is signed, so you can check that it came from KYC and wasn't changed on the way.

## Events

| Event type | Sent when |
| - | - |
| [`guestcomm.message.created`](https://api-docs.kychospitality.com/api-reference/webhooks/guestcomm-message-created) | A guest message is sent or received, on any channel. |
| [`webhook.ping`](https://api-docs.kychospitality.com/api-reference/webhooks/webhook-ping) | You or KYC ask for a test event. |

Event types are named `module.object.action`.
New event types are added over time, and you only receive the ones you subscribe to.

## Setting up an endpoint

KYC sets up your endpoint. You can't create or change one through the API.

Send KYC:

* **The URL.** It must be HTTPS on port 443, with a publicly trusted certificate.
* **The event types** you want, or all public event types.
* **The property**, or all properties in the brand.
* **An optional credential header**, such as `X-Api-Key: <value>`. KYC sends it with every request, so your endpoint can authenticate KYC before it checks the signature.

KYC gives you a **signing secret** that starts with `whsec_`.
It is shown only once, so store it securely, for example in a secrets manager.
Ask KYC for a [ping](https://api-docs.kychospitality.com/api-reference/webhooks/webhook-ping.md) to test your endpoint.

## What a request looks like

```http theme={null}
POST /kyc-webhooks HTTP/1.1
Host: hooks.example.com
Content-Type: application/json
User-Agent: KYCH-Webhooks/1.0
webhook-id: 0193b2f0-7c1e-7a4b-9f3d-2e6c8a1b5d40
webhook-timestamp: 1761815643
webhook-signature: v1,<base64 signature>
Kyc-Delivery-Id: 0193b2f0-7c20-7d11-8e2a-3f4b5c6d7e8f
```

```json theme={null}
{
  "data": {
    "object": "event",
    "id": "0193b2f0-7c1e-7a4b-9f3d-2e6c8a1b5d40",
    "type": "guestcomm.message.created",
    "apiVersion": "2026-11-01",
    "occurredAt": "2026-10-30T09:14:02.000Z",
    "propertyId": "4a2f0c10-2e7a-4b9d-9b3a-1f0c9e8d7a6b",
    "resource": {
      "object": "guestcomm.message",
      "id": "9c8b1e4f-3a2d-4c5b-8e7f-1a2b3c4d5e6f",
      "threadId": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
      "guestId": "7e6d5c4b-3a29-4180-9f8e-7d6c5b4a3928",
      "direction": "incoming",
      "channel": "sms",
      "providerMessageId": "SM8f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9c"
    }
  },
  "meta": {
    "deliveryId": "0193b2f0-7c20-7d11-8e2a-3f4b5c6d7e8f",
    "attempt": 1,
    "timestamp": "2026-10-30T09:14:03.120Z"
  }
}
```

The body uses the same `{ data, meta }` envelope as API responses:

* **`data` is the event.** It is identical on every retry. Its `id` is also the `webhook-id` header.
* **`meta` is this delivery attempt.** It changes on every retry.

## Payloads carry IDs, not content

`data.resource` holds IDs and metadata only.
It never contains message text, attachments, or guest personal data such as names, phone numbers or email addresses.

Use the IDs to fetch the details you need through the API, with your usual credentials.
This keeps [personal information](https://api-docs.kychospitality.com/pii.md) behind API authentication, and you always get current data, even when a retry arrives late.

> [!NOTE]
>
> API endpoints for guest messages are not yet published. Ask KYC about access in the meantime.

## Next steps

* [Verify signatures](https://api-docs.kychospitality.com/webhooks/verifying-signatures.md) on every request.
* Check the [receiver requirements](https://api-docs.kychospitality.com/webhooks/receiver-requirements.md).
* Learn how [retries and auto-disable](https://api-docs.kychospitality.com/webhooks/retries.md) work.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.