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

# Webhook Event Reference

> Route partner webhooks per tenant, process events idempotently, and reconcile outcomes reliably.

# Partner webhook architecture must be tenant-aware by default.

Webhook processing for partner-managed deployments should enforce explicit tenant routing and idempotent writes.

## Core event handling pattern

<Steps>
  <Step title="Receive and persist raw event">
    Store payload with receipt timestamp and original headers for auditability.
  </Step>

  <Step title="Resolve tenant context">
    Map event identifiers to tenant workspace before executing any side effects.
  </Step>

  <Step title="Process asynchronously">
    Fan out to CRM, warehouse, or downstream automation workers with retry-safe jobs.
  </Step>

  <Step title="Mark checkpoint and reconcile">
    Save processing checkpoint and run periodic reconciliation against call logs/export jobs.
  </Step>
</Steps>

## Tenant routing keys

Use one or more of:

* `tenant_id` from webhook payload
* `runtime_vars` business identifiers (`crm_account_id`, `partner_tenant_ref`)
* call identifiers (`call_id`, `voice_session_id`) joined with cached tenant map

## Partner key and tenant key boundaries

* Partner API key: tenant provisioning and cross-tenant administrative operations.
* Tenant API key: tenant-scoped read/write integration tasks.
* Do not execute tenant write-side effects in shared partner context without explicit tenant isolation.

## Reconciliation playbook

Daily reconciliation job should:

1. Pull terminal calls from `voice_sessions`.
2. Compare against processed webhook dedupe records.
3. Replay missing items to downstream systems.
4. Raise incident if mismatch exceeds internal threshold.

## Failure handling

| Failure mode                 | Immediate action                                   | Long-term prevention                       |
| ---------------------------- | -------------------------------------------------- | ------------------------------------------ |
| Duplicate webhook deliveries | Dedupe by `call_id:event` key                      | Enforce uniqueness in storage layer        |
| Cross-tenant misrouting      | Halt worker, quarantine payload                    | Strengthen tenant lookup validation rules  |
| Downstream CRM timeout       | Retry with backoff queue                           | Add circuit breaker and dead-letter review |
| Event backlog spike          | Shed non-critical jobs, prioritize terminal events | Capacity plan worker pool and autoscaling  |

<Note>
  For partner audits, retain raw webhook receipt logs and replay outcomes for at least your agreed operational retention window.
</Note>