Provider Webhooks
Provider Webhooks are inbound messages from a provider Connection into Qanivo. They are owned by the provider worker and adapter boundary, not by an External Consumer subscriber. Provider authenticity must be verified before payload normalization, provider-resource lookup, or Workspace/Connection resolution.
Ingress sequence
- Receive the provider request at the provider-specific ingress.
- Verify the provider signature/token/challenge using the configured Connection secret.
- Reject malformed, replayed, oversized, or unauthenticated input.
- Resolve the configured provider resource and trusted Connection scope.
- Normalize the event into the Qanivo contract and enqueue durable work.
- Acknowledge according to the provider-specific success/retry contract.
Never trust a Workspace ID, Connection ID, sender identity, or resource scope selected inside the payload. The worker must use the authenticated route/configuration and provider-resource binding. A provider event cannot move data across Workspaces.
Provider setup matrix
| Provider family | Authenticity responsibility | Normalization owner | Configuration absent or invalid |
|---|---|---|---|
| WhatsApp HMAC/application verification | WhatsApp worker adapter/payload mapper | Reject or return provider-defined retryable failure; do not accept unsigned data | |
| Telegram | Telegram webhook secret/token policy | Telegram worker adapter | Fail closed and surface provider-limited health |
| Facebook/social providers | Provider-specific challenge/signature | Provider worker adapter | Do not fall back to generic HMAC or claim readiness |
| Other registered providers | Adapter-owned verification contract | Provider worker | Mark unsupported/provider-limited and preserve safe operational evidence |
There is no universal provider signature algorithm. Do not publish provider secrets or copy a provider-specific header rule to another provider.
Operational contract
Provider acknowledgement is not normalized delivery success. Keep provider event IDs and Qanivo correlation metadata for deduplication and diagnosis, while redacting raw bodies and secrets from user-visible responses and logs. See Security, observability, and versioning for retention and safe diagnostics.