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
Receive and persist raw event
Store payload with receipt timestamp and original headers for auditability.
Process asynchronously
Fan out to CRM, warehouse, or downstream automation workers with retry-safe jobs.
Tenant routing keys
Use one or more of:tenant_idfrom webhook payloadruntime_varsbusiness 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:- Pull terminal calls from
voice_sessions. - Compare against processed webhook dedupe records.
- Replay missing items to downstream systems.
- 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 |
For partner audits, retain raw webhook receipt logs and replay outcomes for at least your agreed operational retention window.