Verification

Validate Kirisan webhook POSTs with headers, signing secrets, and fast 2xx responses.

2 min read

Kirisan does not sign webhook bodies with HMAC. Verify deliveries using optional Signing secret headers, event headers, and your own HTTPS endpoint controls.

Signing secret

When you create or edit a webhook on Webhooks → Webhook, you can set Signing secret (optional, up to 512 characters).

On every POST Kirisan includes:

X-Webhook-Secret: the-secret-you-configured

If the header is missing or does not match your stored secret, return 401 or 403 from your handler.

When no secret is configured, Kirisan omits X-Webhook-Secret. Rely on HTTPS and a non-guessable URL path if you skip a secret.

Routing headers

Use these headers before parsing the JSON body:

Header	Value
X-Kirisan-Event	`incoming_message`, `submission`, or `message_status`
X-Kirisan-Device	Device token or identifier for the linked line or bot

The JSON body repeats event and device, but headers let you route cheaply at the edge.

User-Agent

Traffic	User-Agent
Live delivery	`Kirisan-Webhook/1.0`
Webhooks → Test	`Kirisan-Webhook-Test/1.0`

Respond with 2xx quickly

Kirisan treats 200 or 201 as success. Any other HTTP status, connection error, or timeout is failed on Webhooks → Logs.

Best practice:

Validate X-Webhook-Secret (if used).
Parse JSON and enqueue work on your side.
Return 200 or 201 immediately.
Process the message asynchronously.

Kirisan does not retry failed deliveries.

Production vs test payloads

Field	Test (Webhooks → Test)	Live traffic
`production`	`false`	`true`

Optional: ignore or short-circuit handlers when "production": false so test traffic does not touch production CRM records.

HTTPS URL

Saved webhook URLs must be valid http:// or https:// addresses. Use HTTPS in production.

Kirisan must reach your URL from the public internet — localhost and private networks will fail unless you tunnel (for example ngrok) during development.

Activate before live traffic

New endpoints stay Pending test until Webhooks → Test returns 2xx. Only Active endpoints receive live events (except Telegram Incoming Message auto-activation described in Overview).

Editing an endpoint resets it to Pending test until you test again.

Webhooks overview — events, channels, and delivery rules
Test webhooks — send sample POSTs from the dashboard
Debug a failed delivery — read errors on Webhooks → Logs