Webhooks let approved partners receive important Onyx events in their own systems.
Use webhooks for state changes your app needs to react to, such as consent changes, message outcomes, delivery updates, and lifecycle events.
Endpoint Setup
A webhook endpoint should:
- use HTTPS
- belong to the approved partner
- receive only approved event types
- validate signatures where required
- return a clear success response
- avoid logging sensitive payloads
Use separate endpoints or environments for preview and production.
Event Types
Webhook events can include:
- consent granted
- consent revoked
- consent expired
- message allowed
- message blocked
- delivery updated
- thread state changed
- app review changed
Available event types depend on partner approval and product readiness.
Test Delivery
Partners should test webhook delivery before launch.
A test should confirm:
- endpoint reachability
- signature validation
- event parsing
- idempotent handling
- monitoring and alerting
- retry behavior
Do not wait for a live user action to test the endpoint.
Retries
Onyx can retry failed deliveries where supported.
Partners should make webhook handling idempotent so retries do not create duplicate actions.
If a delivery keeps failing, fix the endpoint before requesting more events.
Delivery History
Delivery history can help partners diagnose failures.
History can show:
- event type
- delivery status
- attempt timing
- failure reason
- retry state
Use delivery history to fix the endpoint, not to infer private user data.
Security
Partners should protect webhook secrets, rotate credentials when needed, and limit access to event logs.
Webhook payloads should be treated as partner operational data, not public content.