Skip to content

Webhooks

Set up endpoints, run tests, read delivery logs, and fix webhook failures.

6 min read

Each section is a numbered task — follow the steps, check You should see, then continue. For the full screen reference, see Webhooks reference.

Add a webhook endpoint

Goal: Register an HTTPS URL that receives Kirisan JSON events.

Start when: Your server endpoint is ready to accept POST requests and return 200 or 201.

  1. Open Webhooks → Webhook and click Add webhook.

    • You should see the New webhook modal with Endpoint, Devices, Events, and Security sections.

New webhook modal

  1. Under Endpoint, enter a Display name and your HTTPS URL (for example https://api.yoursite.com/webhooks/kirisan).

  2. Under Devices, pick the channel tab (WhatsApp, Telegram, or WABA) and select at least one device.

  3. Under Events, check at least one: Incoming Message or Submission (WABA also has Message status).

  4. Optional: set a Signing secret — Kirisan sends it as X-Webhook-Secret on every POST.

  5. Click Save → test.

    • You should see Webhooks → Test open for the new endpoint. Status shows Pending test on Webhooks → Webhook until a test succeeds.

Done when: The endpoint appears in the table with your URL and events.

Activate with a test (Pending test → Active)

Goal: Move the endpoint from Pending test to Active by returning 2xx.

Start when: You landed on Webhooks → Test after saving (or endpoint shows Pending test).

  1. Open Webhooks → Test and pick your endpoint in the Webhook dropdown.

    • Labels show name · device · event · URL. Unverified endpoints include pending in the label.

Webhook test form

  1. Review Payload preview — confirm the JSON shape matches what your handler expects.

  2. Click Send test.

    • You should see a result card: Success or Failed, HTTP status, duration, and response body.

Successful webhook test

  1. On Success, go to Webhooks → Webhook and confirm the endpoint shows Active.

Done when: Status is Active on Webhooks → Webhook.

One successful test activates every endpoint from the same Save → test batch. You do not need to test each endpoint separately.

Test a submission webhook

Goal: Verify the Submission event payload before a real form completes.

Start when: You enabled Submission on the endpoint and linked the device that owns the autoreply form.

  1. On Webhooks → Test, select the row whose label includes submission.
  2. Confirm Payload preview includes submission, answers, and "production": false.
  3. Click Send test and confirm Success.
  4. Optional: complete a real test submission on the linked device and compare results on Webhooks → Logs.

Done when: Your handler parses the sample answers array without errors.

Add a device to an existing endpoint

Goal: Send events from a new device to a URL you already have.

  1. On Webhooks → Webhook, click Edit on the endpoint row.
  2. Switch channel tabs and select the additional device.
  3. Click Save → test and run a successful test if status reset to Pending test.
  4. Confirm the Devices count on the row updated.

Done when: Live traffic arrives for each linked device.

Inspect a failed delivery

Goal: Understand why Kirisan could not deliver a webhook and what to fix on your server.

  1. Open Webhooks → Logs and set All statuses to Failed.

    • You should see only rows where the server returned a non-2xx code, timed out, or could not be reached.

Webhook logs — filter by failed status

  1. Optional: filter All devices to narrow to one line or bot.

  2. Click a failed row.

    • You should see Webhook delivery with HTTP code, Duration, Device, and an Error panel.

Failed delivery detail

  1. Read Error and HTTP code:

    • 503 / 502 — server rejected or was overloaded
    • 401 / 403 — check X-Webhook-Secret if you set a signing secret
    • 0 or timeout — Kirisan could not connect; verify DNS, TLS, and firewall

  2. Fix your handler, send a new test from Webhooks → Test, then confirm a success row in Webhooks → Logs.

Done when: The latest attempt shows success.

Debug deliveries for one device

  1. Open Webhooks → Logs.
  2. In All devices, pick the device (labels show name + number or bot name).
  3. Scan Webhook and URL columns to confirm the right endpoint fired.
  4. Click any row for full device and timing details.

Fix common problems

Symptom: No webhooks yet — page is empty.

  • You have not saved an endpoint yet — click Add webhook.
  • You may be on the wrong account — check the email in the top bar.

Symptom: Status stays Pending test.

  • Open Webhooks → Test and send a test — your URL must return 200 or 201.
  • Confirm the URL is HTTPS and reachable from the public internet.
  • Check Webhooks → Logs for TLS or timeout errors.

Symptom: Test succeeds but live messages never arrive.

  • Confirm endpoint status is Active (not Pending test) on Webhooks → Webhook.
  • For Incoming Message: open the device edit dialog and set On incoming message → Webhook. The device must use Webhook as its inbound handler or no events fire.
  • Live traffic uses "production": true — confirm your handler does not reject production payloads.

Symptom: Incoming Message never fires on live traffic.

  • Confirm On incoming message → Webhook is set on the device (not Autoreply, Flow, or Spreadsheet).
  • Confirm the device is linked on the endpoint and the endpoint is Active.
  • Only checked events fire — enable Incoming Message in the endpoint editor.

Symptom: Submission event never fires.

  • Enable Submission on the endpoint and link the device that owns the autoreply form.
  • Use event name submission in new integrations (legacy rows may show submission.completed in the stored value; the JSON body always uses "event": "submission").

Symptom: Test returns 401 or 403.

  • When you set a signing secret, your handler must read X-Webhook-Secret from the request headers.
  • Allow test payloads with "production": false if your handler filters on that field.

Symptom: Test returns timeout or connection error.

  • Confirm the URL is HTTPS and reachable from the public internet (not localhost or a private IP).
  • Check TLS certificate validity.
  • Review Webhooks → Logs for the same error text.

Symptom: Log list is empty even though the endpoint is active.

  • Reset all filters (All events, All statuses, All channels, All devices).
  • For Incoming Message events, confirm the device uses On incoming message → Webhook in device settings.
  • Trigger a real message or use Webhooks → Test, then refresh Webhooks → Logs.

Symptom: Server rejects requests.

  • Parse JSON from the request body. Use X-Kirisan-Event and X-Kirisan-Device headers for routing.
  • When a signing secret is set, compare X-Webhook-Secret to your configured value before processing.
Last updated: July 2, 2026
Was this page helpful?