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

This endpoint requires a business-user JWT (not an API key).

Header	Value
Authorization	Bearer <jwt>

Required roles: BUSINESS_ADMIN, BUSINESS_OWNER, or BUSINESS_DEVELOPER.

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 "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/ivorypay",
    "environment": "LIVE",
    "events": [
      "onramp.success",
      "onramp.failed",
      "offramp.success",
      "offramp.failed",
      "deposit.received",
      "settlement.success"
    ]
  }'

Node.js

const response = await fetch("https://ramp-api.ivorypay.io/api/v1/webhooks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <jwt>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://yourapp.com/webhooks/ivorypay",
    environment: "LIVE",
    events: [
      "onramp.success",
      "onramp.failed",
      "offramp.success",
      "offramp.failed",
      "deposit.received",
      "settlement.success",
    ],
  }),
});

const data = await response.json();
console.log(data);

Python

import requests

response = requests.post(
    "https://ramp-api.ivorypay.io/api/v1/webhooks",
    headers={
        "Authorization": "Bearer <jwt>",
        "Content-Type": "application/json",
    },
    json={
        "url": "https://yourapp.com/webhooks/ivorypay",
        "environment": "LIVE",
        "events": [
            "onramp.success",
            "onramp.failed",
            "offramp.success",
            "offramp.failed",
            "deposit.received",
            "settlement.success",
        ],
    },
)

print(response.json())

Go

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
)

func main() {
	payload := map[string]interface{}{
		"url":         "https://yourapp.com/webhooks/ivorypay",
		"environment": "LIVE",
		"events": []string{
			"onramp.success",
			"onramp.failed",
			"offramp.success",
			"offramp.failed",
			"deposit.received",
			"settlement.success",
		},
	}

	body, _ := json.Marshal(payload)

	req, _ := http.NewRequest("POST", "https://ramp-api.ivorypay.io/api/v1/webhooks", bytes.NewBuffer(body))
	req.Header.Set("Authorization", "Bearer <jwt>")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	respBody, _ := io.ReadAll(resp.Body)
	fmt.Println(string(respBody))
}

Example response

{
  "success": true,
  "message": "Webhook was added successfully",
  "data": {
    "id": "wh-uuid-1",
    "url": "https://yourapp.com/webhooks/ivorypay",
    "environment": "LIVE",
    "events": [
      "onramp.success",
      "onramp.failed",
      "offramp.success",
      "offramp.failed",
      "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.