Webhooks overview
Receive real-time POST JSON from Kirisan when customers message you or complete forms.
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) |
| Not supported — email is outbound-only |
Event types
| Event | Header X-Kirisan-Event | When Kirisan POSTs |
|---|---|---|
incoming_message | incoming_message | A customer sends a message on a linked device with On incoming message → Webhook |
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 |
Legacy rows may still use submission.completed as the stored event name; new integrations should use submission. The JSON body uses "event": "submission" either way.
Payload field reference: Incoming message, Submission, Message 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
- Webhooks → Logs — delivery history and errors
- Send API — outbound messages from your app