Webhooks, Event Subscriptions & Notifications

MITHUNAI webhooks deliver asynchronous HTTP POST notifications to your external endpoints whenever significant lifecycle events occur in your organization. By subscribing to events such as ingestion completion, synchronization failures, or unanswered question detections, engineering teams can automate documentation alerts, synchronize ticketing queues, and trigger internal notifications.

Supported Event Types

Event Name	Trigger Condition	Common Automation
`knowledge.sync.completed`	An asynchronous source ingestion job commits successfully.	Notify developer channels that new documentation is live.
`knowledge.sync.failed`	An ingestion job encounters network errors, parser limits, or broken URLs.	Alert DevOps and knowledge owners via PagerDuty or Slack.
`analytics.unanswered.flagged`	A user query triggers an honest abstention due to missing facts.	Create a Jira or Linear task for technical writers to fill the gap.
`widget.thread.started`	A visitor opens an interaction thread on an embedded website widget.	Track real-time visitor engagement in internal analytics.
`widget.thread.escalated`	A visitor requests human assistance or gives negative feedback.	Route conversation context to Zendesk or live support desks.

Webhook Payload Structure

All webhook payloads are delivered with a standard JSON envelope:

Webhook Event Payload Example

{
  "event": "analytics.unanswered.flagged",
  "id": "evt_01j8k982f10",
  "timestamp": "2026-09-27T05:30:00Z",
  "organization_id": "org_acme_corp",
  "data": {
    "question": "How do I configure mutual TLS for private endpoints?",
    "assistant_id": "asst_prod_01",
    "channel": "widget",
    "abstention_reason": "INSUFFICIENT_EVIDENTIARY_SUPPORT",
    "retrieved_candidate_count": 4,
    "top_similarity_score": 0.42
  }
}

Verifying Webhook Signatures

To verify that webhook requests genuinely originate from MITHUNAI and were not tampered with in transit, inspect the X-MithunAI-Signature header:

Signature Verification Example (Node.js)

import crypto from 'node:crypto'

export function verifyWebhookSignature(
  rawBody: string,
  signatureHeader: string,
  webhookSecret: string,
): boolean {
  const hmac = crypto.createHmac('sha256', webhookSecret)
  const computedSignature = `sha256=${hmac.update(rawBody).digest('hex')}`

  return crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(computedSignature))
}

Delivery Guarantees & Retry Policy

At-Least-Once Delivery: MITHUNAI guarantees that every triggered event is delivered to healthy endpoints.
Retry Schedule: If your server returns an HTTP status outside the 2xx range, the webhook dispatcher retries with exponential backoff at 10 seconds, 1 minute, 5 minutes, and 1 hour.
Timeout: The webhook dispatcher waits up to 10 seconds for an HTTP response before marking an attempt as timed out.

Get started

Knowledge

Assistants & Agents

Channels & Integration

Architecture & Solutions

Administration

Trust and support

Webhooks, Event Subscriptions & Notifications

Supported Event Types

Webhook Payload Structure

Verifying Webhook Signatures

Delivery Guarantees & Retry Policy

​Supported Event Types

​Webhook Payload Structure

​Verifying Webhook Signatures

​Delivery Guarantees & Retry Policy

Supported Event Types

Webhook Payload Structure

Verifying Webhook Signatures

Delivery Guarantees & Retry Policy