Webhooks overview

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`	A guest message is sent or received, on any channel.
`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 to test your endpoint.

What a request looks like

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

{
  "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 behind API authentication, and you always get current data, even when a retry arrives late.

API endpoints for guest messages are not yet published. Ask KYC about access in the meantime.

Next steps

Verify signatures on every request.
Check the receiver requirements.
Learn how retries and auto-disable work.

Getting Started

Authentication & Security

Core Concepts

Using the API

Webhooks

Events

Setting up an endpoint

What a request looks like

Payloads carry IDs, not content

Next steps

​Events

​Setting up an endpoint

​What a request looks like

​Payloads carry IDs, not content

​Next steps

Events

Setting up an endpoint

What a request looks like

Payloads carry IDs, not content

Next steps