> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mithunai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks, Event Subscriptions & Notifications

> Receive real-time HTTP callbacks when ingestion syncs finish, unanswered questions are flagged, or customer widget threads are escalated.

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.

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
flowchart LR
    EVENT["Platform Event\n(Sync Finished / Unanswered Query)"]
    WH["MITHUNAI Webhook Dispatcher\n(HMAC-SHA256 Signed)"]
    DEST["Your Endpoint\n(Slack Bot / PagerDuty / Webhook URL)"]

    EVENT --> WH --> DEST
```

***

## 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:

```json Webhook Event Payload Example theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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:

```typescript Signature Verification Example (Node.js) theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.