AI Chatbot Webhooks & API Tokens
Receive signed bot events and read bots, sessions, messages, exports, and leads through the developer API.
Bot webhooks
A bot webhook receives POST events for leads, messages, and escalations. Verify X-K2Chat-Signature with the displayed secret using HMAC-SHA256. Escalation events include an explicit reason and urgent flag so integrations can distinguish manual escalation, distress safety, follow-up request, and follow-up contact events.
The Delivery Log records event, HTTP status, destination URL, and fired time so failed integrations can be diagnosed. When a follow-up contact email is available, the escalation event can include that contact_email value.
Developer API
- Create and revoke personal API tokens.
- Assign only the required bots:read, conversations:read, and leads:read permissions.
- List accessible bots with a token that has bots:read.
- List sessions, read messages, or export a conversation with conversations:read.
- List captured leads with leads:read.
- Use the complete endpoint reference at k2mailer.com/help/api for paths, pagination, examples, and responses.
Treat tokens and webhook secrets as credentials
Store them in server-side secret management and rotate or revoke them if exposed.
Verifying webhook signatures correctly
Always verify the X-K2Chat-Signature header before trusting a payload; computing the HMAC-SHA256 digest server-side and comparing it in constant time protects your integration from spoofed events sent by anyone who happens to guess your endpoint URL.
Treat retries idempotently. If a delivery fails and is retried, your endpoint should safely process the same event twice, typically by keying on the event ID rather than assuming each POST is unique.
Frequently asked questions
- What is the difference between a bot webhook and the developer API?
- The webhook pushes real-time events such as leads, messages, and escalations to your endpoint; the developer API is a pull-based interface for reading bots, sessions, messages, exports, and leads on demand.
- How do I tell a distress escalation apart from a normal follow-up request?
- Escalation events include an explicit reason and an urgent flag, so a manual escalation, a distress safety event, and a routine follow-up request are all distinguishable in the payload.
- What scopes should a read-only reporting integration request?
- Request only the permissions the integration needs, typically bots:read, conversations:read, and leads:read, rather than issuing a broader token than the use case requires.
Developer reference
Open the complete API reference
Review authentication, parameters, rate limits, cURL requests, and example responses.
Was this guide enough?
Contact support if your screen or result is different.