Webhooks

{
  "id": "cmjh39i5x0000v814e7owtybc",
  "url": "https://yourapp.com/webhooks/orafi",
  "secret": "whsec_a79ab7ad5d9ae565...1bcb3",
  "events": ["payment.success", "payment.failed"],
  "createdAt": "2025-12-22T11:44:41.780Z",
  "updatedAt": "2025-12-22T11:44:41.780Z",
  "profileId": "84a9f045-8a21-4ce4-a7a0-828265c0021b"
}

The webhook object

A webhook is a callback configuration that tells Orafi where to deliver event notifications. Each business profile can have one active webhook.

string

Unique identifier for the webhook configuration.

string

Publicly accessible HTTPS endpoint that receives event payloads.

string

Shared secret used to sign webhook payloads. Use this to verify that incoming requests originate from Orafi.

string[]

Event types the webhook is subscribed to. Only listed events are delivered.

datetime

When the webhook was created.

datetime

When the webhook was last updated.

string

Business profile that owns this webhook.

Available event types

Event	Description
`payment.success`	A payment was completed successfully
`payment.failed`	A payment attempt failed

{
  "id": "cmjh39i5x0000v814e7owtybc",
  "url": "https://yourapp.com/webhooks/orafi",
  "secret": "whsec_a79ab7ad5d9ae565...1bcb3",
  "events": ["payment.success", "payment.failed"],
  "createdAt": "2025-12-22T11:44:41.780Z",
  "updatedAt": "2025-12-22T11:44:41.780Z",
  "profileId": "84a9f045-8a21-4ce4-a7a0-828265c0021b"
}

Get webhook details

GET /webhook

Returns the current webhook configuration for the authenticated profile.

curl -X GET https://api.orafi.app/webhook \
  -H "x-api-key: ora_test_your_api_key"

const response = await fetch("https://api.orafi.app/webhook", {
  headers: { "x-api-key": "ora_test_your_api_key" }
});

import requests

response = requests.get(
    "https://api.orafi.app/webhook",
    headers={"x-api-key": "ora_test_your_api_key"}
)

{
  "success": true,
  "message": "Webhook retrieved successfully",
  "data": {
    "id": "cmjh39i5x0000v814e7owtybc",
    "url": "https://yourapp.com/webhooks/orafi",
    "secret": "whsec_a79ab7ad5d9ae5653ee11ae8b16061080da41031f3fc22811eb2865757a1bcb3",
    "events": ["payment.success", "payment.failed"],
    "createdAt": "2025-12-22T11:44:41.780Z",
    "updatedAt": "2025-12-22T11:44:41.780Z",
    "profileId": "84a9f045-8a21-4ce4-a7a0-828265c0021b"
  }
}

Get event types

GET /webhook/events

Returns all event types available for webhook subscriptions.

curl -X GET https://api.orafi.app/webhook/events \
  -H "x-api-key: ora_test_your_api_key"

const response = await fetch("https://api.orafi.app/webhook/events", {
  headers: { "x-api-key": "ora_test_your_api_key" }
});

import requests

response = requests.get(
    "https://api.orafi.app/webhook/events",
    headers={"x-api-key": "ora_test_your_api_key"}
)

{
  "success": true,
  "message": "Webhook events fetched successfully",
  "data": [
    { "name": "Payment Success", "type": "payment.success" },
    { "name": "Payment Failed", "type": "payment.failed" }
  ]
}

Register a webhook

POST /webhook/register

Registers or updates the webhook endpoint for your business profile. Orafi generates a secret automatically that you can use to verify payloads.

Request body

string

required

Publicly accessible HTTPS URL to receive webhook events.

curl -X POST https://api.orafi.app/webhook/register \
  -H "Content-Type: application/json" \
  -H "x-api-key: ora_test_your_api_key" \
  -d '{
    "url": "https://yourapp.com/webhooks/orafi"
  }'

const response = await fetch("https://api.orafi.app/webhook/register", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "ora_test_your_api_key"
  },
  body: JSON.stringify({
    url: "https://yourapp.com/webhooks/orafi"
  })
});

import requests

response = requests.post(
    "https://api.orafi.app/webhook/register",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "ora_test_your_api_key"
    },
    json={"url": "https://yourapp.com/webhooks/orafi"}
)

{
  "success": true,
  "message": "Webhook updated successfully",
  "data": {
    "id": "cmjh39i5x0000v814e7owtybc",
    "url": "https://yourapp.com/webhooks/orafi",
    "secret": "whsec_a79ab7ad5d9ae5653ee11ae8b16061080da41031f3fc22811eb2865757a1bcb3",
    "events": ["payment.success", "payment.failed"],
    "createdAt": "2025-12-22T11:44:41.780Z",
    "updatedAt": "2025-12-22T11:44:41.780Z",
    "profileId": "84a9f045-8a21-4ce4-a7a0-828265c0021b"
  }
}

POST /webhook/subscribe

Adds an event type to your existing webhook subscription.

Request body

string

required

The event type to subscribe to (e.g. payment.failed).

curl -X POST https://api.orafi.app/webhook/subscribe \
  -H "Content-Type: application/json" \
  -H "x-api-key: ora_test_your_api_key" \
  -d '{
    "event": "payment.failed"
  }'

const response = await fetch("https://api.orafi.app/webhook/subscribe", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-api-key": "ora_test_your_api_key"
  },
  body: JSON.stringify({ event: "payment.failed" })
});

import requests

response = requests.post(
    "https://api.orafi.app/webhook/subscribe",
    headers={
        "Content-Type": "application/json",
        "x-api-key": "ora_test_your_api_key"
    },
    json={"event": "payment.failed"}
)

{
  "success": true,
  "message": "Subscribed to event successfully",
  "data": null
}

Overview

Transactions

Payments

Refunds

Payouts

Paylinks

Customers

Subscriptions

Webhook Deliveries

Crypto Settlements

Fiat Settlements

Profile

Mode

Notifications

Extras

Webhooks

The webhook object

Available event types

Get webhook details

Get event types

Register a webhook

Request body

Request body

​The webhook object

​Available event types

​Get webhook details

​Get event types

​Register a webhook

​Request body

​Subscribe to an event

​Request body

The webhook object

Available event types

Get webhook details

Get event types

Register a webhook

Request body

Subscribe to an event

Request body