Webhook HTTP and error reference
Request and response basics
Use HTTPS, explicit Content-Type, bounded bodies, correlation headers, and the contract version required by the selected webhook surface. Verify authenticity before parsing. A receiver should return a clear HTTP class:
| Response | Meaning | Sender behavior |
|---|---|---|
2xx | Verified envelope durably accepted | Mark transport accepted; do not infer business conversion |
400/422 | Permanent body/schema/mapping rejection | Do not retry unchanged input |
401/403 | Authentication, signature, or scope rejection | Fail closed; rotate/fix configuration before retry |
404 | Destination/resource no longer available | Apply surface policy; may become terminal/disabled |
409 | Idempotency conflict or stale state | Inspect prior result and do not duplicate side effects |
429 | Rate limited | Honor bounded Retry-After and sender policy |
5xx/timeout | Temporary transport failure | Retry under bounded backoff, then terminal/dead-letter |
POST /receiver HTTP/1.1
Content-Type: application/json
X-Correlation-Id: <YOUR_CORRELATION_ID>
X-Qanivo-Webhook-Version: 1.0
X-Qanivo-Webhook-Signature: sha256=<YOUR_SIGNATURE>
{"eventType":"lead.created","data":{"reference":"<YOUR_RESOURCE_REFERENCE>"}}
Safe errors
Error responses may expose a stable code, retryability, terminal state, retry delay, and correlation ID. They must not expose stack traces, raw provider responses, URL resolution details, credentials, signing secrets, or unredacted payloads.