Webhooks

Webhooks

Receive events on your server and verify that they come from Monerails.

Operators and card networks answer in seconds or minutes, never instantly. Instead of polling, give Monerails an HTTPS URL: it sends an event there each time something happens.

Set up an endpoint

In the dashboard under Developers › Webhooks, choose a preset: All events, Payments (collections, payouts, settlements) or Cards (cards and cardholders). For a finer selection, such as collection.* only, use the API:

bash

curl https://api.monerails.com/v1/webhook_endpoints \
  -H "Authorization: Bearer $MONERAIL_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/webhooks/monerail", "events": ["collection.*", "payout.*"]}'

The URL must be HTTPS, with a domain name (IP addresses are refused) and without user:password@. Otherwise the request fails with 400 url_invalid.

The 201 response contains the endpoint’s signing secret (whsec_…). Store it now: it is never shown again, not even if you replay the request with the same Idempotency-Key. If you lose it, rotate it. Test and live endpoints are separate, each with its own secret; live endpoints need an approved business verification. Your business can have up to 10 endpoints, test and live together.

What you receive

A POST with a JSON body, the event:

JSON

{
  "id": "3ab70bfc-785d-45ce-99de-fd9ab67e5cd4",
  "object": "event",
  "type": "collection.succeeded",
  "livemode": false,
  "created_at": "2026-10-30T13:47:58.723Z",
  "data": {
    "object": {
      "id": "3b8f6c1e-2a47-4d1b-9e35-7c0a9d2f4e61",
      "object": "collection",
      "status": "succeeded",
      "amount": 5000,
      "fee": 125,
      "net": 4875,
      "currency": "XAF",
      "client_reference": "order_42"
    }
  }
}

data.object is the full object, in the same format as the API, in its state when the event is delivered. Webhook events shows a complete example for each family.

Header	Content
`Monerail-Signature`	`t=<timestamp>,v1=<signature>`, with a second `v1` while a secret rotation overlaps
`Monerail-Event-Id`	The event ID.
`Monerail-Event-Type`	The event type.
`Monerail-Delivery-Attempt`	1 for the first attempt, then 2, 3…
`User-Agent`	`Monerail-Webhooks/1.0`

Verify the signature

Anyone can send a request to your URL. Before trusting an event, check its signature:

Read t (Unix time, in seconds) and every v1 from Monerail-Signature. There is usually one; there are two while a secret rotation overlaps.
Compute HMAC-SHA256 of t + "." + raw body with your endpoint secret (the whole string, whsec_ included) as key, in lowercase hexadecimal.
Compare it to each v1 in constant time and accept the event if one matches. Refuse events whose t is more than 5 minutes away from your clock: a captured request cannot be replayed later.

Use the raw body, exactly as received: parsing then re-serialising the JSON changes the bytes and breaks the signature. The curl tab sends a correctly signed test event to your local server.

# Send a test event to your local endpoint, signed exactly as Monerails signs it
SECRET="whsec_..."   # the secret of the endpoint you are testing
BODY='{"id":"3ab70bfc-785d-45ce-99de-fd9ab67e5cd4","object":"event","type":"collection.succeeded","livemode":false,"created_at":"2026-10-30T13:47:09.807Z","data":{"object":{"id":"3b8f6c1e-2a47-4d1b-9e35-7c0a9d2f4e61","object":"collection","status":"succeeded"}}}'
T=$(date +%s)
SIG=$(printf '%s' "$T.$BODY" | openssl dgst -sha256 -hmac "$SECRET" -hex | sed 's/^.* //')

# replace the URL with your endpoint
curl http://localhost:3000/webhooks/monerail \
  -H "Content-Type: application/json" \
  -H "Monerail-Signature: t=$T,v1=$SIG" \
  -d "$BODY"

import crypto from 'node:crypto';
import express from 'express';

const SECRET = process.env.MONERAIL_WEBHOOK_SECRET; // whsec_…
const TOLERANCE = 300; // seconds

export function verifySignature(rawBody, header, secret, now = Math.floor(Date.now() / 1000)) {
  let ts = '';
  const signatures = []; // two v1 values while a secret rotation overlaps
  for (const item of (header || '').split(',')) {
    const i = item.indexOf('=');
    if (i <= 0) continue;
    const key = item.slice(0, i).trim(), value = item.slice(i + 1).trim();
    if (key === 't') ts = value;
    if (key === 'v1') signatures.push(value);
  }
  const t = Number(ts);
  if (!/^\d+$/.test(ts) || !signatures.length || Math.abs(now - t) > TOLERANCE) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${ts}.`).update(rawBody).digest();
  return signatures.some((sig) => {
    const received = Buffer.from(sig, 'hex');
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

const app = express();

// express.raw keeps the body as a Buffer: never let a JSON parser touch it first
app.post('/webhooks/monerail', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verifySignature(req.body, req.get('Monerail-Signature'), SECRET)) return res.sendStatus(400);
  const event = JSON.parse(req.body.toString('utf8'));
  res.sendStatus(200); // answer first, then process
  handleEvent(event); // your code: deduplicate by event.id
});

app.listen(3000);

import hashlib
import hmac
import json
import os
import time

from flask import Flask, abort, request

SECRET = os.environ["MONERAIL_WEBHOOK_SECRET"]  # whsec_…
TOLERANCE = 300  # seconds


def verify_signature(raw_body: bytes, header: str, secret: str, now: float | None = None) -> bool:
    items = [item.strip().split("=", 1) for item in (header or "").split(",") if "=" in item]
    t = next((v for k, v in items if k == "t"), "")
    signatures = [v for k, v in items if k == "v1"]  # two v1 values while a secret rotation overlaps
    if not t.isdigit() or not signatures:
        return False
    if abs((now if now is not None else time.time()) - int(t)) > TOLERANCE:
        return False
    expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(expected.encode(), s.encode()) for s in signatures)


app = Flask(__name__)


@app.post("/webhooks/monerail")
def monerail_webhook():
    raw = request.get_data()  # raw bytes, before any JSON parsing
    if not verify_signature(raw, request.headers.get("Monerail-Signature", ""), SECRET):
        abort(400)
    event = json.loads(raw)
    handle_event(event)  # your code: deduplicate by event["id"], keep it fast
    return "", 200

<?php
function verify_signature(string $rawBody, string $header, string $secret, int $tolerance = 300): bool
{
  $t = '';
  $signatures = []; // two v1 values while a secret rotation overlaps
  foreach (explode(',', $header) as $item) {
    $kv = explode('=', trim($item), 2);
    if (count($kv) !== 2) {
      continue;
    }
    if ($kv[0] === 't') {
      $t = $kv[1];
    } elseif ($kv[0] === 'v1') {
      $signatures[] = $kv[1];
    }
  }
  if (!ctype_digit($t) || !$signatures || abs(time() - (int) $t) > $tolerance) {
    return false;
  }
  $expected = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
  foreach ($signatures as $signature) {
    if (hash_equals($expected, $signature)) {
      return true;
    }
  }
  return false;
}

$raw = file_get_contents('php://input'); // raw body, before any JSON parsing
$secret = getenv('MONERAIL_WEBHOOK_SECRET'); // whsec_…
if (!verify_signature($raw, $_SERVER['HTTP_MONERAIL_SIGNATURE'] ?? '', $secret)) {
  http_response_code(400);
  exit;
}
$event = json_decode($raw, true);
http_response_code(200);
// your code: deduplicate by $event['id']

package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"io"
	"net/http"
	"os"
	"strconv"
	"strings"
	"time"
)

const tolerance = 5 * time.Minute

func verifySignature(rawBody []byte, header, secret string, now time.Time) bool {
	var ts string
	var sigs []string // two v1 values while a secret rotation overlaps
	for _, item := range strings.Split(header, ",") {
		k, v, ok := strings.Cut(strings.TrimSpace(item), "=")
		if !ok {
			continue
		}
		switch k {
		case "t":
			ts = v
		case "v1":
			sigs = append(sigs, v)
		}
	}
	t, err := strconv.ParseInt(ts, 10, 64)
	if err != nil || len(sigs) == 0 {
		return false
	}
	if d := now.Sub(time.Unix(t, 0)); d > tolerance || d < -tolerance {
		return false
	}
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write([]byte(ts + "."))
	mac.Write(rawBody)
	expected := hex.EncodeToString(mac.Sum(nil))
	for _, sig := range sigs {
		if hmac.Equal([]byte(expected), []byte(sig)) {
			return true
		}
	}
	return false
}

func monerailWebhook(w http.ResponseWriter, r *http.Request) {
	raw, err := io.ReadAll(io.LimitReader(r.Body, 1<<20)) // raw body, before any JSON parsing
	if err != nil {
		http.Error(w, "unreadable body", http.StatusBadRequest)
		return
	}
	secret := os.Getenv("MONERAIL_WEBHOOK_SECRET") // whsec_…
	if !verifySignature(raw, r.Header.Get("Monerail-Signature"), secret, time.Now()) {
		http.Error(w, "invalid signature", http.StatusBadRequest)
		return
	}
	var event struct {
		ID   string          `json:"id"`
		Type string          `json:"type"`
		Data json.RawMessage `json:"data"`
	}
	if err := json.Unmarshal(raw, &event); err != nil {
		http.Error(w, "invalid JSON", http.StatusBadRequest)
		return
	}
	w.WriteHeader(http.StatusOK)
	// your code: deduplicate by event.ID, then process
}

func main() {
	http.HandleFunc("POST /webhooks/monerail", monerailWebhook)
	http.ListenAndServe(":3000", nil)
}

import com.sun.net.httpserver.HttpServer;
import java.net.InetSocketAddress;
import java.nio.charset.StandardCharsets;
import java.security.GeneralSecurityException;
import java.security.MessageDigest;
import java.util.HexFormat;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class Webhooks {
    static final long TOLERANCE_SECONDS = 300;

    static boolean verifySignature(byte[] rawBody, String header, String secret) {
        String t = null;
        java.util.List<String> signatures = new java.util.ArrayList<>(); // two v1 values while a secret rotation overlaps
        for (String item : (header == null ? "" : header).split(",")) {
            String[] kv = item.trim().split("=", 2);
            if (kv.length != 2) continue;
            if (kv[0].equals("t")) t = kv[1];
            if (kv[0].equals("v1")) signatures.add(kv[1]);
        }
        if (t == null || signatures.isEmpty() || !t.matches("\\d{1,12}")) return false;
        if (Math.abs(System.currentTimeMillis() / 1000 - Long.parseLong(t)) > TOLERANCE_SECONDS) return false;
        try {
            Mac mac = Mac.getInstance("HmacSHA256");
            mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
            mac.update((t + ".").getBytes(StandardCharsets.UTF_8));
            byte[] expected = HexFormat.of().formatHex(mac.doFinal(rawBody)).getBytes(StandardCharsets.UTF_8);
            for (String v1 : signatures) {
                if (MessageDigest.isEqual(expected, v1.getBytes(StandardCharsets.UTF_8))) return true;
            }
            return false;
        } catch (GeneralSecurityException e) {
            throw new IllegalStateException(e);
        }
    }

    public static void main(String[] args) throws Exception {
        String secret = System.getenv("MONERAIL_WEBHOOK_SECRET"); // whsec_…
        HttpServer server = HttpServer.create(new InetSocketAddress(3000), 0);
        server.createContext("/webhooks/monerail", exchange -> {
            byte[] raw = exchange.getRequestBody().readAllBytes(); // raw body, before any JSON parsing
            String header = exchange.getRequestHeaders().getFirst("Monerail-Signature");
            boolean valid = "POST".equals(exchange.getRequestMethod()) && verifySignature(raw, header, secret);
            exchange.sendResponseHeaders(valid ? 200 : 400, -1);
            exchange.close();
            if (valid) {
                // your code: parse raw with your JSON library, deduplicate by id, then process
            }
        });
        server.start();
    }
}

require "json"
require "openssl"
require "sinatra"

TOLERANCE = 300 # seconds

def verify_signature(raw_body, header, secret, now: Time.now.to_i)
  items = header.to_s.split(",").map { |item| item.strip.split("=", 2) }.select { |kv| kv.size == 2 }
  t = items.find { |k, _| k == "t" }&.last
  signatures = items.select { |k, _| k == "v1" }.map(&:last) # two v1 values while a secret rotation overlaps
  return false unless t&.match?(/\A\d+\z/) && signatures.any?
  return false if (now - t.to_i).abs > TOLERANCE

  expected = OpenSSL::HMAC.hexdigest("SHA256", secret, "#{t}.".b + raw_body.b)
  signatures.any? { |sig| (OpenSSL.fixed_length_secure_compare(expected, sig) rescue false) }
end

post "/webhooks/monerail" do
  raw = request.body.read # raw body, before any JSON parsing
  halt 400 unless verify_signature(raw, request.env["HTTP_MONERAIL_SIGNATURE"], ENV.fetch("MONERAIL_WEBHOOK_SECRET"))

  event = JSON.parse(raw)
  # your code: deduplicate by event["id"], then process
  status 200
end

using System.Security.Cryptography;
using System.Text;
using System.Text.Json;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();
var secret = Environment.GetEnvironmentVariable("MONERAIL_WEBHOOK_SECRET")!; // whsec_…

app.MapPost("/webhooks/monerail", async (HttpRequest request) =>
{
    using var buffer = new MemoryStream();
    await request.Body.CopyToAsync(buffer); // raw body, before any JSON parsing
    var raw = buffer.ToArray();
    if (!Webhook.VerifySignature(raw, request.Headers["Monerail-Signature"].ToString(), secret))
        return Results.BadRequest();

    using var evt = JsonDocument.Parse(raw);
    // your code: deduplicate by evt.RootElement.GetProperty("id"), then process
    return Results.Ok();
});

app.Run("http://localhost:3000");

static class Webhook
{
    const long ToleranceSeconds = 300;

    public static bool VerifySignature(byte[] rawBody, string header, string secret)
    {
        string? t = null;
        var signatures = new List<string>(); // two v1 values while a secret rotation overlaps
        foreach (var item in header.Split(','))
        {
            var kv = item.Trim().Split('=', 2);
            if (kv.Length != 2) continue;
            if (kv[0] == "t") t = kv[1];
            if (kv[0] == "v1") signatures.Add(kv[1]);
        }
        if (t is null || signatures.Count == 0 || !long.TryParse(t, out var timestamp)) return false;
        if (Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - timestamp) > ToleranceSeconds) return false;

        using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
        var signed = Encoding.UTF8.GetBytes(t + ".").Concat(rawBody).ToArray();
        var expected = Encoding.UTF8.GetBytes(Convert.ToHexString(hmac.ComputeHash(signed)).ToLowerInvariant());
        return signatures.Any(v1 => CryptographicOperations.FixedTimeEquals(expected, Encoding.UTF8.GetBytes(v1)));
    }
}

Rotate the secret

Roll the signing secret of an endpoint with POST /v1/webhook_endpoints/{id}/rotate_secret (Owner or Developer). The response contains the new secret: store it, it is not shown again.

The old secret keeps working for overlap_minutes (24 hours by default, 0 to 10080, that is 7 days). During that time, every delivery is signed with both secrets: Monerail-Signature: t=…,v1=<new>,v1=<old>. Deploy the new secret, then let the overlap end. Use overlap_minutes: 0 to revoke the old secret immediately, for example after a leak. One rotation per minute at most per endpoint.

bash

curl https://api.monerails.com/v1/webhook_endpoints/we_…/rotate_secret \
  -H "Authorization: Bearer $MONERAIL_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"overlap_minutes": 1440}'

Deliveries and retries

Answer with a 2xx status within 10 seconds. Anything else, a timeout or a redirect counts as a failure (redirects are not followed).
After a failure, Monerails tries again after 1 minute, 5 minutes, 30 minutes, 2 hours, 5 hours, 10 hours and 24 hours: 8 attempts in all, over about 42 hours. After the last one, the delivery is marked failed.
If your domain resolves to a private, loopback, link-local or reserved address, the delivery fails with “destination not allowed” and is retried like any other failure.
Events usually leave within 15 seconds, but not always in order, and the same event can arrive more than once.
To send an event again, use Redeliver an event (up to 10 times per event per hour). The dashboard has no redeliver button.

Good practices

Answer first, process after. Put the event in a queue and return 200 right away.
Deduplicate with the event id: store the IDs you have processed and ignore repeats.
Trust the status, not the order. Base your logic on data.object.status, or fetch the object with the API when in doubt.
Catch up after an outage with List events.
Reconcile periodically with List transactions.

Event types

Type	data.object	Description
`collection.succeeded`	`collection`	A collection succeeded and the net amount was credited to your balance.
`collection.failed`	`collection`	A collection failed (customer declined, insufficient funds, wrong code…).
`collection.expired`	`collection`	The customer did not approve the collection in time.
`payout.succeeded`	`payout`	A payout reached the recipient.
`payout.failed`	`payout`	A payout failed. The amount and the fee were returned to your balance.
`settlement.succeeded`	`settlement`	A settlement reached your settlement account.
`settlement.failed`	`settlement`	A settlement failed. The amount was returned to your balance.
`cardholder.created`	`cardholder`	A cardholder was created.
`cardholder.kyc_updated`	`cardholder`	The identity verification of a cardholder changed status. Read `verification.status`.
`card.created`	`card`	A card was requested.
`card.issued`	`card`	The issuer issued the card. It is active.
`card.issue_failed`	`card`	The issuer could not issue the card. The initial funding was returned to your cards balance.
`card.frozen`	`card`	A card was frozen.
`card.unfrozen`	`card`	A card was unfrozen.
`card.terminated`	`card`	A card was terminated. Its remaining balance returned to your cards balance.
`card.funded`	`transaction`	A card was funded from the cards balance.
`card.withdrawn`	`transaction`	Money was withdrawn from a card back to the cards balance.
`card.transaction`	`transaction`	A card payment was made.
`card.refunded`	`transaction`	A merchant refunded a card payment.
`card.reversed`	`transaction`	A card payment was reversed before settlement.
`card.authorization_declined`	`authorization`	A card payment attempt was declined. `data.object` is `{ object: "authorization", card, amount, currency, merchant, reason }`, with the full card.
`cards_balance.credited`	`transaction`	Your cards balance was credited.

Subscribe to * for everything, or to a family with collection.*, payout.*, card.*… New event types can appear: ignore the ones you do not handle.

Set up an endpoint#

What you receive#

Verify the signature#

Rotate the secret#

Deliveries and retries#

Good practices#

Event types#