ONYX
Docs

Webhooks API

Create webhook endpoints, rotate signing secrets, list events, and replay eligible events.

Webhooks API lets approved partners receive Onyx events on their own servers.

Use it to create endpoints, rotate signing secrets, review event history, and replay eligible events after a delivery issue.

Your webhook handler should validate signatures, process events idempotently, and avoid logging sensitive payloads.

List Endpoints

GET /v1/partner/webhook-endpoints

Returns webhook endpoints for your partner account.

Create Endpoint

POST /v1/partner/webhook-endpoints

Request body:

{
  "url": "https://partner.example.com/hooks/onyx",
  "eventTypes": ["order.created", "esim.ready"]
}

The URL should use HTTPS in production and belong to your organization.

If eventTypes is empty, Onyx creates the endpoint without event filtering.

Rotate Signing Secret

POST /v1/partner/webhook-endpoints/{endpointId}/rotate-secret

Use this endpoint when a signing secret may be exposed, a team member leaves, or your security policy requires rotation.

Store the new secret securely and update your webhook validator before retiring the old secret.

List Events

GET /v1/partner/webhook-events

Returns webhook events and delivery history for your partner account.

Replay Event

POST /v1/partner/webhook-events/{eventId}/replay

Use replay after you fix a failed endpoint or need to restore an event your system missed.

Do not replay events blindly. Confirm your handler is idempotent first.

Event Types

Current event types are:

  • order.created
  • order.provisioning
  • esim.ready
  • esim.downloaded
  • esim.installed
  • package.usage_threshold
  • package.exhausted
  • package.expired
  • order.refunded
  • order.failed

Security

Webhook events use X-Onyx-Partner-Signature with the signing scheme returned for the event.

Protect signing secrets. Do not put them in client-side code, public repositories, analytics tools, support tickets, screenshots, or customer-visible logs.