Webhooks send Onyx events to your server.
Use webhooks to update your systems when orders change, activation material becomes ready, usage crosses a threshold, service expires, a refund completes, a message outcome changes, or consent changes.
Your webhook handler should be secure, idempotent, and safe to retry.
Endpoint Setup
A webhook endpoint should use HTTPS, belong to the partner, receive only configured event types, validate signatures where required, return a clear success response, and avoid logging sensitive payloads.
Use separate endpoints or environment controls for sandbox and live traffic.
Event Types
Configured webhook events include:
- order created
- order provisioning
- service ready
- service downloaded
- service installed
- usage threshold reached
- package exhausted
- package expired
- order refunded
- order failed
- consent granted
- consent revoked
- consent expired
- message allowed
- message blocked
- delivery updated
- thread state changed
- app review changed
Available event types depend on partner configuration and production readiness.
Test Delivery
Test webhook delivery before launch.
A test should confirm endpoint reachability, signature validation, event parsing, idempotent handling, monitoring, alerting, and retry behavior.
Do not wait for a live customer action to test the endpoint.
Retries
Onyx retries eligible failed deliveries.
Make webhook handling idempotent so retries do not create duplicate actions.
If a delivery keeps failing, fix the endpoint before requesting more events or replaying old ones.
Delivery History
Delivery history helps partners diagnose failures.
History includes event type, delivery status, attempt timing, failure reason, and retry state.
Use delivery history to fix the endpoint, not to infer private customer data.
Security
Protect webhook secrets, rotate credentials when needed, and limit access to event logs.
Webhook payloads are partner operational data, not public content.