Webhooks - Monirates

Webhooks allow your system to receive real-time event notifications from Monirates. When key events happen — like a payment or currency exchange — Monirates sends an HTTP POST request with a JSON payload to your registered URL.

Setup Overview

All webhook configuration happens in your Monirates dashboard:

Log in at business.monirates.com (or dev.business.monirates.com for sandbox).
Navigate to Settings.
Generate your API Key and Secret Key.
Register your Webhook URL.

Step 1: Generate Your API Key

Your API key authorizes requests and enables your webhook to receive events. Include it in your request headers:

x-api-key: MR_v1_your_unique_api_key

Step 2: Generate Your Secret Key

The Secret Key is used to verify that incoming webhook events genuinely originate from Monirates. Every webhook delivery includes a signature header:

x-monirates-signature: <signature>

The signature is computed using HMAC SHA256 over the raw request body combined with your Secret Key.

Validating the Signature

Always validate the signature before processing any webhook event.

const crypto = require('crypto');

const signature = req.headers['x-monirates-signature'];

const computed = crypto
  .createHmac('sha256', process.env.MONIRATES_SECRET_KEY)
  .update(JSON.stringify(req.body))
  .digest('hex');

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

// Safe to process the event

import hmac
import hashlib
import json
import os

secret_key = os.environ.get("MONIRATES_SECRET_KEY").encode()
signature = request.headers.get("x-monirates-signature")

body = json.dumps(request.json, separators=(',', ':')).encode()
computed = hmac.new(secret_key, body, hashlib.sha256).hexdigest()

if not hmac.compare_digest(computed, signature):
    return {"error": "Invalid signature"}, 401

# Safe to process the event

$secretKey = getenv('MONIRATES_SECRET_KEY');
$signature = $_SERVER['HTTP_X_MONIRATES_SIGNATURE'];

$body = file_get_contents('php://input');
$computed = hash_hmac('sha256', $body, $secretKey);

if (!hash_equals($computed, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

// Safe to process the event

Never share your Secret Key. Store it securely as an environment variable and never commit it to version control.

Step 3: Register Your Webhook URL

Your webhook endpoint must:

Accept POST requests
Receive JSON payloads
Be publicly accessible over HTTPS

Retry Behavior

If Monirates cannot reach your endpoint, deliveries are retried automatically:

Attempt	Behavior
1st	Initial delivery
2nd	Retry after delay
3rd	Final retry after increased delay
After 3rd failure	Retries stop

Manual Retry via API

You can also view and retry failed webhook events programmatically:

Method	Endpoint	Description
`GET`	`/webhooks`	List all webhook events
`GET`	`/webhook/{webhookId}`	View details of a specific event
`POST`	`/webhook/{webhookId}/retry`	Manually retry a failed event

Security Requirements

Two headers are used to secure webhook communication:

Header	Purpose
`x-api-key`	Authorizes the incoming webhook request
`x-monirates-signature`	Validates authenticity and payload integrity

Always reject webhook events that are missing or have an invalid x-monirates-signature. Do not process unsigned events.

Event Types & Sample Payloads

Payment Link Event

Triggered when a payment link transaction is initiated or updated.

{
  "_id": "690df12b358c9311463ac6d4",
  "userId": "67e5345cdce758f487ab6ca6",
  "userGlobalId": "6976ea90-0afd-11f0-8cd1-296b05bbd448",
  "amount": 105500,
  "currencyIso2": "NG",
  "paymentDetails": {
    "accountName": "MONIRATES LIMITED",
    "accountNumber": "0115847370",
    "providerName": "MTN",
    "bankCode": "90221",
    "paymentMethod": "BANK_TRANSFER",
    "currency": "NGN"
  },
  "payerDetails": {
    "name": "Monirates",
    "email": "info@monirates.com"
  },
  "status": "PENDING",
  "source": "API",
  "globalId": "f7cfd470-bbdb-11f0-9062-8dd914a47085",
  "createdAt": "2025-11-07T13:16:27.986Z"
}

Currency Exchange Event

Triggered when a currency exchange transaction is initiated or completed.

{
  "_id": "68ff77732efaebbdad28c843",
  "globalId": "2fd81ca0-b33b-11f0-82b7-2929f12a03df",
  "offerId": "68b5a636793705d3cc1578e7",
  "buyerGlobalId": "6976ea90-0afd-11f0-8cd1-296b05bbd448",
  "fromCurrency": "GBP",
  "toCurrency": "NGN",
  "rate": 1972.2,
  "fee": 0,
  "amount": 200,
  "status": "SUCCESSFUL",
  "buyerDebitPaymentMethod": "BANK_TRANSFER",
  "buyerCreditPaymentMethod": "BANK_TRANSFER",
  "buyerCreditPaymentDetails": {
    "accountName": "MONIRATES LIMITED",
    "accountNumber": "0115847370",
    "providerName": "SAFE HAVEN SANDBOX BANK",
    "bankCode": "999240",
    "paymentMethod": "BANK_TRANSFER",
    "iso2": "NG",
    "currency": "NGN"
  },
  "buyerDebitPaymentDetails": {
    "accountName": "MONIRATES LIMITED",
    "accountNumber": "0115847370",
    "providerName": "1234567",
    "bankCode": "1234567",
    "paymentMethod": "BANK_TRANSFER",
    "iso2": "GB",
    "currency": "GBP"
  },
  "sellerCreditPaymentDetails": {
    "accountName": "Rahama Rahama",
    "accountNumber": "2580369147",
    "providerName": "5566447755",
    "bankCode": "5566447755",
    "paymentMethod": "BANK_TRANSFER",
    "iso2": "GB",
    "currency": "GBP",
    "isUssdCode": false
  },
  "source": "API",
  "buyerMadePayment": true,
  "hasBuyerPaymentProof": false,
  "buyerPaymentProofUrl": null,
  "paymentReferenceCode": 938663,
  "createdAt": "2025-10-27T13:45:23.941Z",
  "updatedAt": "2025-10-27T13:55:26.972Z"
}

Fetching Webhook Logs

Beyond the API, you can also view webhook delivery history directly in the Monirates dashboard — filter by SUCCESSFUL or FAILED and track retry attempts for reconciliation.

Need help integrating? Reach out to the Monirates support team from your dashboard.

​Setup Overview

​Step 1: Generate Your API Key

​Step 2: Generate Your Secret Key

​Validating the Signature

​Step 3: Register Your Webhook URL

​Retry Behavior

​Manual Retry via API

​Security Requirements

​Event Types & Sample Payloads

​Payment Link Event

​Currency Exchange Event

​Fetching Webhook Logs

Setup Overview

Step 1: Generate Your API Key

Step 2: Generate Your Secret Key

Validating the Signature

Step 3: Register Your Webhook URL

Retry Behavior

Manual Retry via API

Security Requirements

Event Types & Sample Payloads

Payment Link Event

Currency Exchange Event

Fetching Webhook Logs