API authentication and webhooks
API keys
Section titled “API keys”Create a separate key for each integration and grant only the required scopes. Store it in a server-side secret manager and revoke it immediately if exposed.
For create operations, send a unique idempotency key where the endpoint supports one. Reusing the key with the same request returns the existing outcome rather than creating another record.
Verify webhook signatures
Section titled “Verify webhook signatures”Webhook requests include:
X-Qonvera-Event-IdX-Qonvera-TimestampX-Qonvera-Signature: sha256=<hex digest>
Compute HMAC-SHA256 over timestamp + "." + rawBody using the endpoint signing secret. Compare the digest with a constant-time comparison, reject stale timestamps, and preserve the unmodified raw request body until verification is complete.
Return a 2xx only after safely accepting or idempotently recognizing the event. Return a retryable 5xx for temporary failures. Store processed event IDs so repeated delivery cannot duplicate work.
Delivery operations
Section titled “Delivery operations”The Developers page shows recent attempts, HTTP status, and delivery state. After fixing the receiving endpoint, use Resend for failed or retryable deliveries. The scheduled dispatcher must be authenticated when invoking Qonvera’s internal delivery route.