Webhooks

Webhooks let your application react to events that happen after a Unified API request. Use them for delivery receipts, OTP verification status, internal order updates, and support alerts. Configure webhooks from Unified API > Webhooks in the customer dashboard. The list is paginated at 20 rows per page so large accounts stay easy to manage.

When to Use Webhooks

Use webhooks when your system needs to know what happened after KarFlows accepted a request:

A Unified message was sent, failed, or routed through fallback.
An OTP was accepted, verified, expired, or failed.
A message finally used SMS after WhatsApp QR or Meta failed.

Events

Event	Meaning
`message.sent`	A Unified message was accepted by at least one channel
`message.failed`	All selected delivery channels failed
`message.routed`	KarFlows finished route evaluation and logged all attempts
`sms.sent`	SMS was the successful channel
`sms.failed`	SMS was attempted and failed
`otp.sent`	Unified OTP was accepted by at least one selected channel
`otp.verified`	The customer entered the correct OTP
`otp.failed`	OTP delivery or verification failed
`otp.expired`	OTP verification failed because the code expired

Payload Shape

KarFlows sends a JSON body like this:

{
  "id": "kfwh_1778175301000_k9x2abp1",
  "event": "message.sent",
  "createdAt": "2026-05-07T12:00:00.000Z",
  "data": {
    "reference": "omni_1778175300000_a1b2c3",
    "to": "255700000000",
    "messageType": "text",
    "status": "sent",
    "winningChannel": "whatsapp_qr",
    "deliveryMode": "fallback",
    "requestedChannels": ["whatsapp_qr", "whatsapp_meta", "sms"],
    "attempts": [
      { "channel": "whatsapp_qr", "success": true, "messageId": "3EB0..." }
    ]
  }
}

Headers

Every webhook request includes:

Header	Description
`User-Agent`	`KarFlows-Webhooks/1.0`
`X-KarFlows-Event`	Event name, for example `message.sent`
`X-KarFlows-Delivery`	Unique delivery id
`X-KarFlows-Timestamp`	Unix timestamp in seconds
`X-KarFlows-Signature`	HMAC SHA-256 signature

Signature Verification

When you create a webhook, KarFlows shows the signing secret once. Store it securely. KarFlows signs:

timestamp.raw_json_body

The signature format is:

sha256=<hex_digest>

Node.js Example

import crypto from "crypto";
import express from "express";

const app = express();

app.post(
  "/karflows/webhook",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const secret = process.env.KARFLOWS_WEBHOOK_SECRET;
    const timestamp = req.get("X-KarFlows-Timestamp");
    const received = req.get("X-KarFlows-Signature") || "";
    const body = req.body.toString("utf8");

    const expected =
      "sha256=" +
      crypto
        .createHmac("sha256", secret)
        .update(`${timestamp}.${body}`)
        .digest("hex");

    const valid =
      received.length === expected.length &&
      crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));

    if (!valid) {
      return res.status(401).send("invalid signature");
    }

    const event = JSON.parse(body);
    console.log("KarFlows event", event.event, event.data);

    return res.sendStatus(200);
  }
);

Recommended Response

Return any 2xx status when your application accepts the event.

return res.sendStatus(200);

If your endpoint returns a non-2xx status or times out, KarFlows marks that webhook delivery as failed in the dashboard. Store the webhook id or data.reference and ignore duplicates.

message.sent, sms.sent, and otp.sent report immediate channel acceptance. They are not final handset delivery receipts.

Local Development

Webhook URLs must be publicly reachable. Localhost URLs are blocked. For development, use a public tunnel such as ngrok, Cloudflare Tunnel, or a staging domain.

Dashboard Controls

In the Unified API Webhooks tab, a customer can:

Add endpoint URL and display name.
Select events to listen for.
Enable or disable an endpoint.
Rotate the signing secret.
Send a test webhook.
Delete endpoints that are no longer used.

Admins can see customer endpoints and recent deliveries from the SMS & OTP Gateway dashboard.

Start Here

Messaging APIs

Operations

SDKs

Reference

When to Use Webhooks

Events

Payload Shape

Headers

Signature Verification

Node.js Example

Recommended Response

Local Development

Dashboard Controls

​When to Use Webhooks

​Events

​Payload Shape

​Headers

​Signature Verification

​Node.js Example

​Recommended Response

​Local Development

​Dashboard Controls

When to Use Webhooks

Events

Payload Shape

Headers

Signature Verification

Node.js Example

Recommended Response

Local Development

Dashboard Controls