Configure your webhooks

Webhook setup follows a simple workflow:

Create a webhook endpoint (created as inactive by default).
Enable the webhook once your server is ready to receive events.
(Optional) Update subscribed events or disable the webhook at any time.

Requirements

Before creating a webhook endpoint, ensure the following:

The destination URL must be publicly accessible
The URL must use the HTTPS protocol
At least one event must be specified
Duplicate events are not allowed
Your endpoint must respond with a 2xx status code to acknowledge receipt

Step 1 — Create a webhook endpoint

Create a webhook by specifying the destination url and the list of events to subscribe to.

curl -X POST https://sandbox.orbipayments.com/v1/webhooks \
  -H "Content-Type: application/json" \
  -H "x-api-key: ak_sandbox_xxxxx..." \
  -d '{
    "url": "https://merchant.example.com/webhooks/orbi",
    "events": ["order:created", "order:updated", "order:paid", "payment:applied", "payment:failed", "payment:refunded"]
  }'

Behavior

Newly created webhooks are returned as inactive (is_enabled=false)
No events are delivered until the webhook is explicitly enabled

Step 2 — Enable the webhook endpoint

Once your webhook consumer is deployed and ready to receive events, enable the webhook.

curl -X PATCH https://sandbox.orbipayments.com/v1/webhooks/whk_xxxxxxx \
  -H "Content-Type: application/json" \
  -H "x-api-key: ak_sandbox_xxxxx..." \
  -d '{
    "is_enabled": true
  }'

Step 3 — Update events or disable a webhook (optional)

You can modify the subscribed events or disable a webhook at any time.

Update subscribed events

curl -X PATCH https://sandbox.orbipayments.com/v1/webhooks/whk_xxxxxxx \
  -H "Content-Type: application/json" \
  -H "x-api-key: ak_sandbox_xxxxx..." \
  -d '{
    "events": ["order:created", "order:updated", "order:paid"],
    "is_enabled": true
  }'

Disable a webhook

curl -X PATCH https://sandbox.orbipayments.com/v1/webhooks/whk_xxxxxxx \
  -H "Content-Type: application/json" \
  -H "x-api-key: ak_sandbox_xxxxx..." \
  -d '{
    "is_enabled": false
  }'

Supported webhook events

You can subscribe to the following event types:

Event type	Description
`order:created`	Emitted when a new order is created.
`order:updated`	Emitted when an existing order is updated.
`order:paid`	Emitted when an order is fully paid.
`payment:applied`	Emitted when a payment is applied to an order.
`payment:failed`	Emitted when a payment attempt fails.
`payment:refunded`	Emitted when a payment is refunded.

Event payload

Webhook events are delivered as JSON payloads with the following structure:

{
  "event": "order:paid",
  "data": {},
  "object_type": "object",
  "timestamp": 1713206400123
}

Payload fields

event — The event type that triggered the webhook.
data — The resource associated with the event (Order or Payment).
object_type — The type of the object included in data.
timestamp — Unix timestamp in milliseconds, indicating when the event was generated.

The structure of the data object matches the corresponding API resource representation.

Webhook request headers

Each webhook delivery includes the following HTTP headers:

Content-Type: application/json
x-signature: <signature>
x-timestamp: <timestamp>
x-idempotency-key: <idempotency-key>

The x-timestamp header matches the timestamp field included in the payload.

Acknowledging events

Your endpoint must respond with an HTTP 2xx status code to acknowledge successful receipt of a webhook event.

If a non-2xx response is returned or the request times out, the delivery may be retried.