Choose a webhook surface
Qanivo uses “webhook” for several different contracts. Select the surface by direction and ownership before writing code.
| Surface | Direction | Integrator role | Qanivo route/ownership | Authentication/signing | Retry model | Status |
|---|---|---|---|---|---|---|
| Provider Webhook | Provider → Qanivo | Provider connection operator | Provider-specific worker ingress | Provider-specific verification before normalization | Provider/provider-worker acknowledgement and redelivery rules | provider-limited |
| Qanivo Event Hook | Qanivo → subscriber | External Consumer administrator | /api/external/v1 subscription and delivery services | Scoped External Consumer identity plus Qanivo signature | Delivery attempts, bounded retries, disablement | supported |
| Workflow Webhook Action | Workflow → target | Workspace Workflow designer | Governed Workflow action dispatcher | Workspace authorization; current handler adds no Qanivo signature | Workflow attempt/retry and terminal failure | not-verified |
| Lead Delivery | Qanivo → destination | Lead delivery administrator | Lead Delivery Subscription/attempt ownership | Current URL policy accepts HTTP/HTTPS; worker adds lead-delivery signature when configured | Independent bounded attempts and terminal outcome | supported |
These surfaces do not share credentials, payload ownership, or success semantics. A Provider Webhook is inbound provider traffic; an Event Hook and Lead Delivery are outbound Qanivo deliveries; a Workflow Webhook Action is one governed step in a Workflow run.
Start here
- Qanivo Event Hooks and External Consumers
- Provider Webhooks
- Workflow Webhook Actions
- Lead Delivery
- Signing and verification
- Retries, idempotency, and failures
- Security, observability, and versioning
- HTTP and errors
- Versioning
Common rules
- Resolve the trusted Workspace/Connection/External Consumer scope from authenticated context, never from a payload-selected identifier.
- Validate authenticity, replay, schema, bounds, and authorization before accepting or delivering data.
- Treat normalized status and delivery outcome as explicit values; transport success is not CRM acceptance, conversion, or provider success.
- Keep secrets, raw provider payloads, signing material, and internal topology out of public responses and logs.