Setup Webhook

Configure a webhook URL to receive event notifications.

Registers a webhook URL that will receive event notifications for your business. You can configure separate webhooks for TEST and LIVE environments.

Endpoint

POST /v1/webhooks

Authentication

Header	Value
x-api-key	Your API key

Request body

Field	Type	Required	Description
url	string	Yes	Your webhook endpoint URL (must be a valid HTTPS URL)
environment	string	Yes	Environment: TEST or LIVE
events	string[]	Yes	Array of webhook events to subscribe to (must not be empty, no duplicates)

Example request

cURL

curl -X POST https://ramp-api.ivorypay.io/api/v1/webhooks \
  -H "x-api-key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/ivorypay",
    "environment": "LIVE",
    "events": [
      "onramp.success",
      "onramp.failed",
      "offramp.success",
      "offramp.failed",
      "buy.success",
      "sell.success",
      "deposit.received",
      "settlement.success"
    ]
  }'

Node.js

Python

Go

Example response

{
  "statusCode": 201,
  "success": true,
  "message": "Webhook created successfully",
  "data": {
    "id": "wh-uuid-1",
    "url": "https://yourapp.com/webhooks/ivorypay",
    "environment": "LIVE",
    "events": [
      "onramp.success",
      "onramp.failed",
      "offramp.success",
      "offramp.failed",
      "buy.success",
      "sell.success",
      "deposit.received",
      "settlement.success"
    ],
    "createdAt": "2026-03-26T12:00:00.000Z"
  }
}

Error cases

Scenario	Description
Duplicate webhook	A webhook already exists for this environment
Invalid URL	The URL provided is not a valid URL
Empty events	The events array must contain at least one event

You can only have one webhook per environment (TEST/LIVE). To change it, use Update Webhook.

For the full list of available events, see Webhook Events Reference.