{"templateId":"GuidePage","sharedDataIds":{"sidebar":"sidebar-developers/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["callout","split","playground-button"]},"type":"markdown"},"seo":{"title":"Webhooks","description":"Developer API, partner integration, MCP, SDK, and customer help center.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"webhooks","__idx":0},"children":["Webhooks"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use webhooks to sync CRM data, trigger automations in your stack, notify external systems, or feed event streams into your own analytics pipeline."]},{"$$mdtype":"Tag","name":"Callout","attributes":{"type":"info","title":"MiniApp vs tenant webhooks"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide covers ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["outbound"]}," webhooks (Karzoun notifies your server). For ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["inbound"]}," provider webhooks configured inside MiniApp JSON, see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/miniapps/guides/webhooks"},"children":["MiniApps webhooks"]},"."]}]},{"$$mdtype":"Tag","name":"Callout","attributes":{"type":"info","title":"Where to manage webhooks"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create and inspect subscriptions in ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Developer → Webhooks"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/developer/webhooks"]},") or via GraphQL mutations. Search the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/developers/apis/public-api"},"children":["GraphQL API reference"]}," for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Webhook"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhooksAdd"]},", and related operations."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"how-delivery-works","__idx":1},"children":["How delivery works"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When an event occurs, Karzoun:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Finds every ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["active"]}," webhook subscribed to that ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," + ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action"]}," pair"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Builds a versioned JSON envelope (see ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"#payload-format"},"children":["Payload format"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Signs the raw body and attaches auth headers"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["POSTs to your URL with up to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["3 retry attempts"]}," on failure"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Records every attempt in ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["delivery logs"]}," for debugging"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your endpoint should return any ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["2xx"]}," status within the connection timeout. Non-2xx responses and network errors trigger automatic retries with exponential backoff."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"security","__idx":2},"children":["Security"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Karzoun secures webhook traffic with ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["two independent mechanisms"]}," on every delivery. Use one or both to confirm the request genuinely came from Karzoun."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Mechanism"},"children":["Mechanism"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Header"},"children":["Header"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Purpose"},"children":["Purpose"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Token"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Karzoun-token"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Static bearer token generated when the webhook is created"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HMAC signature"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Karzoun-Signature-256"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sha256="]}," + HMAC-SHA256 of the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["raw request body"]}," using your webhook ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["secret"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["During a ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"#rotate-signing-secret"},"children":["secret rotation"]}," grace period (24 hours), Karzoun also sends ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Karzoun-Signature-256-Previous"]}," signed with the previous secret so you can roll over without downtime."]},{"$$mdtype":"Tag","name":"Callout","attributes":{"type":"warning","title":"Reject unauthenticated requests"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Always verify the token or signature before processing a payload. If neither matches, respond with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," and discard the body."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"verify-the-hmac-signature","__idx":3},"children":["Verify the HMAC signature"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The signature header value is prefixed with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sha256="]},". Strip that prefix, then compare the remainder to an HMAC you compute over the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["exact raw body bytes"]}," (not a re-serialized JSON object)."]},{"$$mdtype":"Tag","name":"Split","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Node.js"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"js","header":{"controls":{"copy":{}}},"source":"const crypto = require('crypto');\n\nfunction verifyKarzounWebhook(req, secret) {\n  const header = req.headers['x-karzoun-signature-256'];\n  if (!header || !header.startsWith('sha256=')) return false;\n\n  const expected = header.slice('sha256='.length);\n  const computed = crypto\n    .createHmac('sha256', secret)\n    .update(req.rawBody, 'utf8') // use the raw body string/buffer\n    .digest('hex');\n\n  return crypto.timingSafeEqual(\n    Buffer.from(expected, 'hex'),\n    Buffer.from(computed, 'hex'),\n  );\n}\n","lang":"js"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["PHP"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"php","header":{"controls":{"copy":{}}},"source":"$secret = getenv('WEBHOOK_SECRET');\n$header = $_SERVER['HTTP_X_KARZOUN_SIGNATURE_256'] ?? '';\n$body = file_get_contents('php://input');\n\nif (!str_starts_with($header, 'sha256=')) {\n  http_response_code(401);\n  exit;\n}\n\n$expected = substr($header, 7);\n$computed = hash_hmac('sha256', $body, $secret);\n\nif (!hash_equals($expected, $computed)) {\n  http_response_code(401);\n  exit;\n}\n\nhttp_response_code(200);\n","lang":"php"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"verify-the-token","__idx":4},"children":["Verify the token"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Compare the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Karzoun-token"]}," header to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["token"]}," returned when you created the webhook. This is a simple shared-secret check — pair it with HMAC verification for defense in depth."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"register-a-webhook","__idx":5},"children":["Register a webhook"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Register subscriptions with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhooksAdd"]},". Karzoun generates a unique ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["token"]}," and HMAC ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["secret"]},", validates your URL (HTTPS + SSRF checks), and sends an automatic ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["connectivity ping"]},"."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["url"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Required."]}," HTTPS endpoint that receives POST requests"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Human-readable label"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["description"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["What this webhook is used for"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["actions"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["array"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Event subscriptions — each entry has ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action"]},", and optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["label"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["retryPolicy.maxAttempts"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["int"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Max delivery attempts (default: ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["3"]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["retryPolicy.backoffMs"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["int[]"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Delay between retries in ms (default: ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["5000, 30000, 120000"]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rateLimitPerMinute"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["int"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Max deliveries per minute per webhook (default: ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["100"]},")"]}]}]}]}]},{"$$mdtype":"Tag","name":"Callout","attributes":{"type":"info","title":"Discover available events"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Query ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhooksGetActions"]}," to list every event your workspace can subscribe to. The catalog below reflects the current platform modules."]}]},{"$$mdtype":"Tag","name":"Split","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["GraphQL"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"graphql","header":{"controls":{"copy":{}}},"source":"mutation {\n  webhooksAdd(\n    url: \"https://api.example.com/karzoun/events\"\n    name: \"CRM + inbox sync\"\n    description: \"Customer and conversation updates\"\n    actions: [\n      { type: \"core:customer\", action: \"create\" }\n      { type: \"core:customer\", action: \"update\" }\n      { type: \"inbox:conversation\", action: \"create\" }\n      { type: \"inbox:conversation\", action: \"assign\" }\n      { type: \"whatsapp:flow\", action: \"completed\" }\n    ]\n    retryPolicy: {\n      maxAttempts: 3\n      backoffMs: [5000, 30000, 120000]\n    }\n  ) {\n    _id\n    url\n    token\n    secret\n    actions { type action label }\n    retryPolicy { maxAttempts backoffMs }\n  }\n}\n","lang":"graphql"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["cURL"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST 'https://YOUR_SUBDOMAIN.api.karzoun.chat/graphql' \\\n  -H 'Content-Type: application/json' \\\n  -H 'x-app-token: YOUR_APP_TOKEN' \\\n  -d '{\n    \"query\": \"mutation { webhooksAdd(url: \\\"https://api.example.com/karzoun/events\\\", name: \\\"My hook\\\", actions: [{ type: \\\"core:customer\\\", action: \\\"update\\\" }]) { _id token secret } }\"\n  }'\n","lang":"bash"},"children":[]}]},{"$$mdtype":"Tag","name":"PlaygroundButton","attributes":{"label":"Register a webhook in Playground","query":"mutation { webhooksAdd(url: \"https://example.com/webhook\", name: \"Test\", actions: [{ type: \"core:customer\", action: \"create\" }]) { _id url token secret } }","variant":"outlined"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Store credentials immediately."]}," The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["token"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["secret"]}," are returned on creation. Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhooksRotateSecret"]}," to roll the HMAC secret; the previous secret remains valid for 24 hours."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"other-management-operations","__idx":6},"children":["Other management operations"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Mutation"},"children":["Mutation"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhooksEdit"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Update URL, name, actions, retry policy, or rate limit"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhooksRemove"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Delete a webhook and its delivery logs"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhooksToggle"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Pause or resume deliveries without deleting config"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhooksRotateSecret"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Generate a new HMAC secret (24h grace on the old one)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhooksPing"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Send a test ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["system.ping"]}," event to verify connectivity"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhooksRetryDelivery"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Manually retry a failed delivery log entry"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhooksReset"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Reset circuit breaker and error counters after fixing your endpoint"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhookDeliveryLogs"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Inspect request/response details for debugging"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"payload-format","__idx":7},"children":["Payload format"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every delivery uses the same envelope shape (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["version"]}," is currently ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1"]}]},"):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"id\": \"550e8400-e29b-41d4-a716-446655440000\",\n  \"version\": \"1\",\n  \"timestamp\": \"2026-06-23T14:30:00.000Z\",\n  \"event\": \"inbox:conversation.create\",\n  \"data\": {\n    \"_id\": \"abc123\",\n    \"status\": \"open\",\n    \"customerId\": \"cust_456\"\n  },\n  \"metadata\": {\n    \"webhookId\": \"wh_789\",\n    \"deliveryId\": \"del_012\",\n    \"attemptNumber\": 1,\n    \"description\": \"Customer has started a new conversation\",\n    \"resourceUrl\": \"https://YOUR_SUBDOMAIN.karzoun.chat/inbox?conversation=abc123\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unique event ID — use as an ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["idempotency key"]}," to deduplicate retries"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fully-qualified name: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["<type>.<action>"]}," (e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["core:customer.update"]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Native JSON object for the affected resource — never double-stringified"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["metadata.attemptNumber"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Which delivery attempt this is (1 = first try)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["metadata.resourceUrl"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Deep link to the resource in the Karzoun UI"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["delete"]}," events, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," is normalized to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ \"type\": \"<type>\", \"object\": { \"_id\": \"...\" } }"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Connectivity pings use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event: \"system.ping\""]}," with a short test message in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]},"."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"retries-timeouts-and-circuit-breaker","__idx":8},"children":["Retries, timeouts, and circuit breaker"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Setting"},"children":["Setting"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Default"},"children":["Default"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Behavior"},"children":["Behavior"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HTTP timeout"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["10 seconds"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Karzoun waits up to 10s for your server to respond"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Max attempts"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["3"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Failed deliveries retry with backoff: 5s → 30s → 2min"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Circuit breaker"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["5 failures"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["After 5 consecutive failures, deliveries pause until cooldown (5 min) or you call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhooksReset"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Rate limit"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["100/min"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Per-webhook cap; excess events are logged as skipped"]}]}]}]}]},{"$$mdtype":"Tag","name":"Callout","attributes":{"type":"caution","title":"Respond quickly"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Return ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2xx"]}," as soon as you have accepted the payload. Offload heavy work to a background queue — slow handlers risk timeouts and retries."]}]},{"$$mdtype":"Tag","name":"Callout","attributes":{"type":"tip","title":"Idempotent handlers"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The same logical event may arrive more than once (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," stays the same across retries; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["metadata.deliveryId"]}," changes per attempt). Design handlers to tolerate duplicates."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"event-catalog","__idx":9},"children":["Event catalog"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Events are identified by a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}]}," (module + resource) and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action"]}]}," (what happened). In the delivered payload they appear as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["event: \"<type>.<action>\""]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Query ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhooksGetActions"]}," for the live list. Subscriptions below are grouped by platform module."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"customers--corecustomer-","__idx":10},"children":["Customers (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["core:customer"]},")"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Event"},"children":["Event"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"action"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["core:customer.create"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A customer record was created"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["core:customer.update"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["update"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A customer record was updated"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["core:customer.delete"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["delete"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A customer record was deleted"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["core:customer.merge"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merge"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Two customer records were merged"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"conversations--inbox--inbox-","__idx":11},"children":["Conversations & inbox (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["inbox:*"]},")"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Event"},"children":["Event"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"action"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["inbox:conversation.create"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A new conversation started"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["inbox:conversation.status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conversation status changed (e.g. open → closed)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["inbox:conversation.assign"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["assign"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conversation assigned to an agent"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["inbox:conversation.unassign"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["unassign"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conversation unassigned"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["inbox:conversation.update"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["update"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conversation metadata updated"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["inbox:feedback.create"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Customer submitted feedback"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["inbox:summary.create"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["AI conversation summary generated"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["inbox:popupSubmitted.create"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Customer submitted a popup form"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"whatsapp--whatsapp-","__idx":12},"children":["WhatsApp (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["whatsapp:*"]},")"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Event"},"children":["Event"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"action"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["whatsapp:order.received"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["received"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Order received via WhatsApp commerce"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["whatsapp:flow.completed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["completed"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["WhatsApp Flow finished by the customer"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"tasks--tasks-","__idx":13},"children":["Tasks (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tasks:*"]},")"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Event"},"children":["Event"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"action"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tasks:task.create"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Task created"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tasks:task.update"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["update"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Task updated"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tasks:task.delete"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["delete"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Task deleted"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tasks:task.assign"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["assign"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Task assigned"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tasks:task.stage_change"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stage_change"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Task moved to a different stage"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tasks:task.priority_change"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["priority_change"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Task priority changed"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tasks:task.due_date"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["due_date"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Task due date changed"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tasks:checklist.item_checked"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["item_checked"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Checklist item marked complete"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"meetings--meetingsmeeting-","__idx":14},"children":["Meetings (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["meetings:meeting"]},")"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Event"},"children":["Event"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"action"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["meetings:meeting.create"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Meeting scheduled"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["meetings:meeting.update"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["update"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Meeting details changed"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["meetings:meeting.cancel"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancel"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Meeting cancelled"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["meetings:meeting.start"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["start"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Meeting started"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"timeclock--timeclock-","__idx":15},"children":["Timeclock (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timeclock:*"]},")"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Event"},"children":["Event"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"action"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timeclock:shift.clock_in"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clock_in"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Employee clocked in"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timeclock:shift.clock_out"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["clock_out"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Employee clocked out"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timeclock:absence.requested"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["requested"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Absence / time-off requested"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timeclock:absence.approved"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["approved"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Absence request approved"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timeclock:absence.rejected"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rejected"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Absence request rejected"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timeclock:schedule.submitted"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["submitted"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Schedule submitted for approval"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timeclock:schedule.approved"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["approved"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Schedule approved"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timeclock:schedule.rejected"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rejected"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Schedule rejected"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"system","__idx":16},"children":["System"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Event"},"children":["Event"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"action"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["action"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["system.ping"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ping"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Connectivity test sent by ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhooksPing"]}," or on webhook creation"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"troubleshooting","__idx":17},"children":["Troubleshooting"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"1-confirm-karzoun-is-sending-events","__idx":18},"children":["1. Confirm Karzoun is sending events"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Open ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Developer → Webhooks → Delivery logs"]}," for the subscription"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Run ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhooksPing"]}," and check for a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["system.ping"]}," delivery with status ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["success"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Temporarily point the URL to ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://webhook.site"},"children":["webhook.site"]}," to inspect raw requests"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"2-check-your-endpoint","__idx":19},"children":["2. Check your endpoint"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Symptom"},"children":["Symptom"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Likely cause"},"children":["Likely cause"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No requests at all"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Webhook paused (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["isActive: false"]},"), circuit open, or wrong event subscription"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," on your side"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Token/signature verification failing — compare raw body, not parsed JSON"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Timeouts"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Handler too slow; Karzoun aborts after ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["10 seconds"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["circuit-open"]}," status"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Five consecutive failures — fix the endpoint, then ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhooksReset"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Skipped deliveries"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Rate limit exceeded for that webhook"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"3-validate-url-requirements","__idx":20},"children":["3. Validate URL requirements"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Must be ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HTTPS"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Must resolve to a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["public"]}," IP (private ranges and localhost are blocked for SSRF protection)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Must return ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["2xx"]}," for Karzoun to consider delivery successful"]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":21},"children":["Next steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/developers/apis/public-api"},"children":["GraphQL API Reference"]}," — search for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Webhook"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["WebhookDeliveryLog"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/developers/getting-started/authentication"},"children":["Authentication"]}," — app tokens for GraphQL access"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"/developers/guides/errors"},"children":["Errors"]}," — interpreting GraphQL and HTTP error responses"]}]},{"$$mdtype":"Tag","name":"PlaygroundButton","attributes":{"label":"List delivery logs in Playground","query":"query { webhooks(page: 1, perPage: 5) { data { _id name url status isActive } } }","variant":"outlined"},"children":[]}]},"headings":[{"value":"Webhooks","id":"webhooks","depth":1},{"value":"How delivery works","id":"how-delivery-works","depth":2},{"value":"Security","id":"security","depth":2},{"value":"Verify the HMAC signature","id":"verify-the-hmac-signature","depth":3},{"value":"Verify the token","id":"verify-the-token","depth":3},{"value":"Register a webhook","id":"register-a-webhook","depth":2},{"value":"Other management operations","id":"other-management-operations","depth":3},{"value":"Payload format","id":"payload-format","depth":2},{"value":"Retries, timeouts, and circuit breaker","id":"retries-timeouts-and-circuit-breaker","depth":2},{"value":"Event catalog","id":"event-catalog","depth":2},{"value":"Customers ( core:customer )","id":"customers--corecustomer-","depth":3},{"value":"Conversations & inbox ( inbox:* )","id":"conversations--inbox--inbox-","depth":3},{"value":"WhatsApp ( whatsapp:* )","id":"whatsapp--whatsapp-","depth":3},{"value":"Tasks ( tasks:* )","id":"tasks--tasks-","depth":3},{"value":"Meetings ( meetings:meeting )","id":"meetings--meetingsmeeting-","depth":3},{"value":"Timeclock ( timeclock:* )","id":"timeclock--timeclock-","depth":3},{"value":"System","id":"system","depth":3},{"value":"Troubleshooting","id":"troubleshooting","depth":2},{"value":"1. Confirm Karzoun is sending events","id":"1-confirm-karzoun-is-sending-events","depth":3},{"value":"2. Check your endpoint","id":"2-check-your-endpoint","depth":3},{"value":"3. Validate URL requirements","id":"3-validate-url-requirements","depth":3},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"title":"Webhooks","titleTranslationKey":"sidebar.developers.webhooks","description":"Subscribe to Karzoun platform events — conversations, customers, WhatsApp flows, tasks, and more.","audience":"developer","status":"published","locales":["en","ar"],"template":"GuidePage","seo":{"title":"Webhooks"}},"lastModified":"2026-06-23T12:06:12.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/developers/guides/webhooks","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}