Webhooks overview
Kirisan webhooks are outbound HTTPS POST requests from Kirisan to a URL you control. They are not part of https://api.kirisan.com — your server receives traffic; Kirisan does not expose a webhook subscription API.
Use webhooks when your CRM, helpdesk, or backend should react to inbound messages or completed autoreply forms without polling the dashboard.
Configure in the dashboard
- Open Webhooks → Webhook and click Add webhook.
- Enter your HTTPS URL, link devices, and choose events.
- Run a successful test on Webhooks → Test so status becomes Active.
See Webhooks reference for the full UI tour and Add a webhook endpoint for a step-by-step tutorial.
Supported channels
| Channel | Webhook events |
|---|---|
| Incoming Message, Submission | |
| Telegram | Incoming Message, Submission |
| WABA | Incoming Message, Submission, Message status (delivery receipts) |
| API | Send Status (optional) — async POST /v1/send notifications to your server (account-wide, no device); Kirisan logs still update automatically |
| Incoming Message — when mail is accepted for a linked sender address |
Event types
| Event | Header X-Kirisan-Event | When Kirisan POSTs |
|---|---|---|
incoming_message | incoming_message | A customer messages a linked chat device, or mail is accepted for a linked email address |
submission | submission | A user completes an autoreply submission form on a linked device |
message_status | message_status | WABA only — Meta delivery/read status for an outbound message |
send_status | send_status | Optional — a POST /v1/send with mode: async finishes; one POST per request (only if you configured an endpoint) |
Payload field reference: Incoming message, Submission, Message status, Send status.
Delivery contract
| Rule | Detail |
|---|---|
| Method | POST |
| Body | application/json |
| Success | Your server returns 200 or 201 |
| Timeout | About 30 seconds per live delivery (45 seconds for Webhooks → Test) |
| Retries | None — Kirisan sends once per event and logs the result on Webhooks → Logs |
| Test vs live | Sample payloads include "production": false; live traffic uses "production": true |
If your server returns any other status, times out, or cannot be reached, the delivery is marked failed. Fix the handler and wait for the next live event, or send another test from Webhooks → Test.
Request headers
Every delivery includes:
Content-Type: application/json
User-Agent: Kirisan-Webhook/1.0
X-Kirisan-Event: incoming_message
X-Kirisan-Device: <device token or number>When you set a Signing secret on the endpoint, Kirisan also sends:
X-Webhook-Secret: <your secret>See Verification for how to validate requests and respond safely.
Telegram note
For Incoming Message on Telegram, Kirisan may auto-activate a Pending test endpoint when the first real message arrives on a linked bot — you still should run Webhooks → Test during setup to confirm your URL early.
Related
- Verification — signing secret, headers, and response rules
- Incoming message payload — WhatsApp, Telegram, and WABA examples
- Send status — async
POST /v1/sendresults - Webhooks → Logs — delivery history and errors
- Send API — outbound messages from your app