Webhooks Overview

Real-time event notifications for your IvoryPay transactions.

Webhooks allow IvoryPay to push real-time notifications to your server whenever an event occurs — such as a payment being received, a crypto payout completing, or a settlement finishing. Instead of polling the API for status updates, your server is notified automatically.

How webhooks work

1. A transaction event occurs (e.g., user pays fiat for an on-ramp)
2. IvoryPay sends an HTTP POST request to your configured webhook URL
3. Your server processes the event and responds with HTTP 200
4. If your server doesn't respond with 200, IvoryPay retries (number of attempts is configured via `app.maxNumInitialTrials`)

Setting up webhooks

Via API

Webhook CRUD endpoints are authenticated with a business-user JWT (not an API key) and require one of the BUSINESS_ADMIN, BUSINESS_OWNER, or BUSINESS_DEVELOPER roles.

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", "offramp.success", "deposit.received"]
  }'

See Setup Webhook for the full API reference.

Webhook payload structure

Every webhook delivery sends a JSON POST request with this structure:

{
  "event": "onramp.success",
  "data": {
    // Event-specific payload — see Events Reference
  }
}

Headers

Header	Description
Content-Type	application/json
x-ivorypay-signature	HMAC-SHA512 signature for verification (see Webhook Security)

Handling webhooks

Your webhook endpoint should:

1. Verify the signature — Validate the x-ivorypay-signature header (see Webhook Security)

2. Return HTTP 200 quickly — Respond within a few seconds to avoid timeouts

3. Process asynchronously — Queue the event for processing rather than doing heavy work inline

4. Be idempotent — You may receive the same event more than once (on retries); handle duplicates gracefully

5. Verify via API — After receiving a webhook, call the Verify Transaction endpoint to confirm the data

Example handler (Node.js / Express)

const crypto = require('crypto');

app.post('/webhooks/ivorypay', express.json(), (req, res) => {
  // 1. Verify signature — IMPORTANT: sign ONLY the inner `data` object,
  // not the full request body. The server computes
  // HMAC-SHA512(JSON.stringify(payload.data)) with your secret key.
  const signature = req.headers['x-ivorypay-signature'];
  const expectedSignature = crypto
    .createHmac('sha512', process.env.IVORYPAY_SECRET_KEY)
    .update(JSON.stringify(req.body.data))
    .digest('hex');

  if (signature !== expectedSignature) {
    return res.status(401).send('Invalid signature');
  }

  // 2. Respond immediately
  res.status(200).send('OK');

  // 3. Process asynchronously
  const { event, data } = req.body;

  switch (event) {
    case 'onramp.success':
      // Credit user's account, send confirmation email, etc.
      handleOnRampSuccess(data);
      break;
    case 'offramp.success':
      handleOffRampSuccess(data);
      break;
    case 'deposit.received':
      handleDepositReceived(data);
      break;
    default:
      console.log(`Unhandled event: ${event}`);
  }
});

Example handler (Python / Flask)

import hmac
import hashlib
import json
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhooks/ivorypay', methods=['POST'])
def handle_webhook():
    # 1. Verify signature — sign ONLY the inner `data` object,
    # not the full request body.
    signature = request.headers.get('x-ivorypay-signature')
    data = request.json.get('data')
    expected = hmac.new(
        os.environ['IVORYPAY_SECRET_KEY'].encode(),
        json.dumps(data).encode(),
        hashlib.sha512
    ).hexdigest()

    if signature != expected:
        return jsonify({'error': 'Invalid signature'}), 401

    # 2. Respond immediately
    event = request.json.get('event')

    # 3. Queue for async processing
    process_event.delay(event, data)  # e.g., Celery task

    return jsonify({'status': 'ok'}), 200

Retry behavior

If your endpoint doesn't respond with HTTP 200, IvoryPay retries delivery:

Attempt	Timing
1st	Immediate
2nd	After delay
3rd	After longer delay

After 3 failed attempts, the webhook delivery is marked as failed. You can check the delivery status in your dashboard.

Best practices

• Always verify signatures — Never trust webhook payloads without signature verification

• Return 200 immediately — Don't process the event before responding

• Use HTTPS — Webhook URLs must be HTTPS in production

• Handle duplicates — Use the reference field to deduplicate events

• Verify via API — Call the verify endpoint before making irreversible actions (crediting accounts, fulfilling orders)

• Log everything — Log all webhook deliveries for debugging and auditing