Webhooks

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Karzoun webhooks deliver real-time HTTP notifications when something changes in your workspace. Register an HTTPS endpoint, pick the events you care about, and Karzoun POSTs a structured JSON payload whenever they fire — for example when a conversation is assigned, a customer is updated, or a WhatsApp flow completes.

Use webhooks to sync CRM data, trigger automations in your stack, notify external systems, or feed event streams into your own analytics pipeline.

How delivery works

When an event occurs, Karzoun:

1. Finds every active webhook subscribed to that type + action pair
2. Builds a versioned JSON envelope (see Payload format)
3. Signs the raw body and attaches auth headers
4. POSTs to your URL with up to 3 retry attempts on failure
5. Records every attempt in delivery logs for debugging

Your endpoint should return any 2xx status within the connection timeout. Non-2xx responses and network errors trigger automatic retries with exponential backoff.

Security

Karzoun secures webhook traffic with two independent mechanisms on every delivery. Use one or both to confirm the request genuinely came from Karzoun.

During a secret rotation grace period (24 hours), Karzoun also sends X-Karzoun-Signature-256-Previous signed with the previous secret so you can roll over without downtime.

Verify the HMAC signature

The signature header value is prefixed with sha256=. Strip that prefix, then compare the remainder to an HMAC you compute over the exact raw body bytes (not a re-serialized JSON object).

const crypto = require('crypto');

function verifyKarzounWebhook(req, secret) {
  const header = req.headers['x-karzoun-signature-256'];
  if (!header || !header.startsWith('sha256=')) return false;

  const expected = header.slice('sha256='.length);
  const computed = crypto
    .createHmac('sha256', secret)
    .update(req.rawBody, 'utf8') // use the raw body string/buffer
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(computed, 'hex'),
  );
}

$secret = getenv('WEBHOOK_SECRET');
$header = $_SERVER['HTTP_X_KARZOUN_SIGNATURE_256'] ?? '';
$body = file_get_contents('php://input');

if (!str_starts_with($header, 'sha256=')) {
  http_response_code(401);
  exit;
}

$expected = substr($header, 7);
$computed = hash_hmac('sha256', $body, $secret);

if (!hash_equals($expected, $computed)) {
  http_response_code(401);
  exit;
}

http_response_code(200);

Verify the token

Compare the Karzoun-token header to the token returned when you created the webhook. This is a simple shared-secret check — pair it with HMAC verification for defense in depth.

Register a webhook

Register subscriptions with webhooksAdd. Karzoun generates a unique token and HMAC secret, validates your URL (HTTPS + SSRF checks), and sends an automatic connectivity ping.

mutation {
  webhooksAdd(
    url: "https://api.example.com/karzoun/events"
    name: "CRM + inbox sync"
    description: "Customer and conversation updates"
    actions: [
      { type: "core:customer", action: "create" }
      { type: "core:customer", action: "update" }
      { type: "inbox:conversation", action: "create" }
      { type: "inbox:conversation", action: "assign" }
      { type: "whatsapp:flow", action: "completed" }
    ]
    retryPolicy: {
      maxAttempts: 3
      backoffMs: [5000, 30000, 120000]
    }
  ) {
    _id
    url
    token
    secret
    actions { type action label }
    retryPolicy { maxAttempts backoffMs }
  }
}

curl -X POST 'https://YOUR_SUBDOMAIN.api.karzoun.chat/graphql' \
  -H 'Content-Type: application/json' \
  -H 'x-app-token: YOUR_APP_TOKEN' \
  -d '{
    "query": "mutation { webhooksAdd(url: \"https://api.example.com/karzoun/events\", name: \"My hook\", actions: [{ type: \"core:customer\", action: \"update\" }]) { _id token secret } }"
  }'

Store credentials immediately. The token and secret are returned on creation. Use webhooksRotateSecret to roll the HMAC secret; the previous secret remains valid for 24 hours.

Other management operations

Payload format

Every delivery uses the same envelope shape (version is currently 1):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "version": "1",
  "timestamp": "2026-06-23T14:30:00.000Z",
  "event": "inbox:conversation.create",
  "data": {
    "_id": "abc123",
    "status": "open",
    "customerId": "cust_456"
  },
  "metadata": {
    "webhookId": "wh_789",
    "deliveryId": "del_012",
    "attemptNumber": 1,
    "description": "Customer has started a new conversation",
    "resourceUrl": "https://YOUR_SUBDOMAIN.karzoun.chat/inbox?conversation=abc123"
  }
}

For delete events, data is normalized to { "type": "<type>", "object": { "_id": "..." } }.

Connectivity pings use event: "system.ping" with a short test message in data.

Retries, timeouts, and circuit breaker

Event catalog

Events are identified by a type (module + resource) and action (what happened). In the delivered payload they appear as event: "<type>.<action>".

Query webhooksGetActions for the live list. Subscriptions below are grouped by platform module.

Customers (core:customer)

Conversations & inbox (inbox:*)

WhatsApp (whatsapp:*)

Tasks (tasks:*)

Meetings (meetings:meeting)

Timeclock (timeclock:*)

System

Troubleshooting

1. Confirm Karzoun is sending events

• Open Developer → Webhooks → Delivery logs for the subscription
• Run webhooksPing and check for a system.ping delivery with status success
• Temporarily point the URL to webhook.site to inspect raw requests

2. Check your endpoint

3. Validate URL requirements

• Must be HTTPS
• Must resolve to a public IP (private ranges and localhost are blocked for SSRF protection)
• Must return 2xx for Karzoun to consider delivery successful

Next steps

• GraphQL API Reference — search for Webhook, WebhookDeliveryLog
• Authentication — app tokens for GraphQL access
• Errors — interpreting GraphQL and HTTP error responses