Guide to Monerium Webhooks: Features and Best Practices
Monerium is a licensed electronic money institution that issues euro e-money tokens, such as EURe, on public blockchains, and links each customer's blockchain addresses to an IBAN. Money moves through orders: an incoming SEPA payment creates an issue order that mints EURe, and an outgoing payment or cross-chain transfer is a redeem order. Orders take time to clear, so Monerium's webhooks tell your application when an order appears and when it is processed or rejected.
Two things make Monerium's setup unusual: you generate the signing secret yourself, and the subscription stays inactive until your endpoint answers a subscription.created event. This guide covers both, along with the order events and how to verify them.
What are Monerium webhooks?
Monerium webhooks are subscriptions you create through the API from a Private plan application, described in Monerium's Private integration guide. The registration call carries the URL, the event types and a secret that you generate. Monerium signs every delivery with that secret, following Standard Webhooks.
Right after registration, Monerium sends a subscription.created event to the URL. Responding 200 OK activates the subscription. From then on, each order change arrives as a JSON POST whose data is the order. Profile approval is not a webhook event; Monerium sends that by email.
Monerium webhook features
| Feature | Details |
|---|---|
| Plan | Private |
| Configuration | API: POST /webhooks with url, secret and types |
| Authentication for the API | Client-credentials access token (1 hour) |
| Activation | Answer subscription.created with 200 OK |
| Signature | Standard Webhooks HMAC-SHA256 |
| Headers | webhook-id, webhook-timestamp, webhook-signature |
| Secret | Generated by you (whsec_ + base64 random bytes) |
| Body | {type, data}, where data is the order |
| Event routing | Body field type |
| Retries | Up to 10 over 12 hours, exponential backoff, until 200 OK |
| Timeout, ordering | Not documented |
| Source IPs | Not published |
Events and payloads
| Event | Triggered When | Common Use Cases |
|---|---|---|
order.created | An order is created, e.g. an incoming payment is detected before it is processed | Notify the customer early that funds are on the way |
order.updated | An order changes state | Mark payments complete on processed (read meta.txHashes), handle rejected (read meta.rejectedReason) |
subscription.created | Immediately after you register the webhook | Answer 200 OK to activate the subscription |
Monerium calls order.updated the primary event. Subscribe to order.created as well if you want to tell a customer that money is on its way before it clears. The guide doesn't call this list complete, and it links API reference pages per event, so acknowledge types you don't recognise.
Monerium prints no example body. Its handler code reads these fields:
| Field | Meaning |
|---|---|
type | The event type, for example order.updated. This is what handlers switch on |
data.id | The order id (not an event id) |
data.state | The order state. The guide acts on processed and rejected |
data.meta | txHashes (on-chain transaction hashes) once processed; rejectedReason when rejected |
Because data.id identifies the order, not the event, several events share it. Deduplicate deliveries on the webhook-id header instead.
Setting up Monerium webhooks
Build against the sandbox first, using a Private application's client ID and secret.
Generate your signing secret and keep it server-side as
MONERIUM_WEBHOOK_SECRET:import crypto from 'crypto'; const secret = 'whsec_' + crypto.randomBytes(32).toString('base64');Get an access token with the client-credentials grant. It expires after an hour:
const response = await fetch('https://api.monerium.dev/auth/token', { method: 'POST', headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, body: new URLSearchParams({ grant_type: 'client_credentials', client_id: 'YOUR_CLIENT_ID', client_secret: 'YOUR_CLIENT_SECRET', }), });Deploy your receiver, verifying with the secret from step 1, before you register. The activation event arrives immediately.
Register the webhook:
await fetch('https://api.monerium.dev/webhooks', { method: 'POST', headers: { Authorization: `Bearer ${access_token}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ url: 'https://your-app.com/webhooks/monerium', secret, // the whsec_ value you generated types: ['order.created', 'order.updated'], }), });Answer the
subscription.createddelivery with200 OK. The subscription is active once you do.
For production, complete KYC or KYB at monerium.app/profiles, create a production application, and register again with a new secret. Private applications don't need partner review. To receive sandbox events locally, run the Hookdeck CLI and register its URL:
npx hookdeck-cli listen 3000 monerium --path /webhooks/monerium
With Hookdeck. Create a Monerium source and register its URL with POST /webhooks. You create the secret when you register the webhook: generate whsec_ followed by base64 random bytes, send it to Monerium and paste the same value here. Hookdeck answers every POST with 200, so the subscription.created event activates the subscription even before your own service is running. The source accepts only POST, and a request whose signature fails is logged as failed verification rather than delivered.
Securing Monerium webhooks
Monerium signs ${webhook-id}.${webhook-timestamp}.${body} with HMAC-SHA256, using the base64-decoded part of your secret after whsec_ as the key, and sends v1,<base64> in webhook-signature. Monerium's sample compares the header with a single value; the verifier below splits on spaces and accepts any v1 entry, which covers both:
const crypto = require('node:crypto');
function decodeBase64(value) {
if (typeof value !== 'string' || !/^[A-Za-z0-9+/]+={0,2}$/.test(value)) return null;
const bytes = Buffer.from(value, 'base64');
return bytes.length > 0 && bytes.toString('base64').replace(/=+$/, '') === value.replace(/=+$/, '')
? bytes : null;
}
function verifySignature(rawBody, headers, secret) {
if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
const prefix = headers['webhook-id'] !== undefined ? 'webhook' : 'svix';
const id = headers[`${prefix}-id`];
const timestamp = headers[`${prefix}-timestamp`];
const signature = headers[`${prefix}-signature`];
if (typeof id !== 'string' || !id || typeof timestamp !== 'string' ||
!/^[0-9]+$/.test(timestamp) || typeof signature !== 'string') return false;
const key = decodeBase64(secret.replace(/^whsec_/, ''));
if (!key) return false;
const message = Buffer.concat([Buffer.from(`${id}.${timestamp}.`, 'utf8'), rawBody]);
const candidates = signature.split(/\s+/).filter((item) => item.startsWith('v1,')).map((item) => item.slice(3));
const expected = crypto.createHmac('sha256', key).update(message).digest();
return candidates.some((candidate) => {
const received = decodeBase64(candidate);
if (!received) return false;
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
});
}
The handler must let subscription.created through with a 200, and it should only treat processed and rejected as final:
const express = require('express');
// Returns the parsed body when it is a JSON object, otherwise null.
function parseJsonObject(rawBody) {
try {
const value = JSON.parse(rawBody.toString('utf8'));
return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
} catch {
return null;
}
}
const app = express();
app.post('/webhooks/monerium', express.raw({ type: '*/*' }), async (req, res) => {
const secret = process.env.MONERIUM_WEBHOOK_SECRET;
if (!secret) return res.sendStatus(500);
if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);
const event = parseJsonObject(req.body);
if (!event) return res.sendStatus(400); // signed, but not a JSON object
if (typeof event.type !== 'string') return res.sendStatus(400);
if (event.type === 'subscription.created') return res.sendStatus(200); // activates the subscription
if (event.type === 'order.updated' && (!event.data || typeof event.data !== 'object')) return res.sendStatus(400);
try {
if (event.type === 'order.updated' && event.data.state === 'processed') {
await payments.markSettled(req.headers['webhook-id'], event.data.id, event.data.meta?.txHashes);
} else if (event.type === 'order.updated' && event.data.state === 'rejected') {
await payments.markRejected(req.headers['webhook-id'], event.data.id, event.data.meta?.rejectedReason);
}
} catch {
return res.sendStatus(503); // not processed, so don't acknowledge
}
return res.sendStatus(200);
});
payments represents your own code, which should ignore a webhook-id it has already handled.
Monerium sets no timestamp tolerance and its sample doesn't check one. If you verify with a Standard Webhooks library instead, its default 5-minute window applies. Hookdeck checks no timestamp age and forwards Monerium's original webhook-timestamp on retries and replays, so that library window would reject redelivered events behind Hookdeck. Leave the age check out, as in the function above.
Make Monerium webhooks production-ready. Hookdeck Event Gateway verifies Monerium's signatures with your own secret, activates the subscription for you, and keeps every order event until your service has recorded it.
Monerium webhook limitations and pain points
Activation depends on your endpoint being ready
The Problem: You register a webhook and no order events ever arrive.
Why It Happens: The subscription only activates once subscription.created gets a 200 OK. If your receiver isn't deployed yet, rejects the event's signature because it has a different secret, or returns an error for an unknown type, activation fails.
Workarounds:
- Deploy the receiver with the same secret before calling
POST /webhooks. - Answer
subscription.createdwith200explicitly.
How Hookdeck Can Help: Hookdeck returns 200 to every request, so activation succeeds regardless of the state of your service.
You own the secret
The Problem: The secret is lost, or differs between Monerium and your verifier.
Why It Happens: Monerium never generates or displays a secret; it uses whatever you sent at registration.
Workarounds:
- Generate, store and register the secret in one script, and keep separate secrets for sandbox and production.
How Hookdeck Can Help: Paste the same value into the Hookdeck source once, and every consumer behind it is covered.
Retries end after 12 hours
The Problem: An outage longer than half a day loses order updates.
Why It Happens: Monerium retries up to 10 times over 12 hours, then stops.
Workarounds:
- After an outage, list recent orders through the API and reconcile.
How Hookdeck Can Help: Hookdeck accepts each event immediately and retries delivery to your service for as long as you configure.
No published payloads
The Problem: You can't build fixtures or validate fields against an example.
Why It Happens: Monerium's guide shows handler code but no delivery body.
Workarounds:
- Capture events in the sandbox and use them as fixtures.
How Hookdeck Can Help: Hookdeck stores each sandbox delivery with its headers, ready to inspect and replay.
Best practices
Verify against the raw body
Monerium's own handler uses express.raw({ type: 'application/json' }). '*/*' also works, as do await request.text() in a Next.js handler and await request.body() in FastAPI.
Settle only on processed
Treat order.created as information. Credit balances or release goods only when order.updated reports processed, and record meta.txHashes for reconciliation.
Deduplicate on webhook-id
Monerium names it the de-duplication key; data.id is the order and repeats across events. See our idempotency guide.
Keep tokens server-side
The client secret, access tokens and webhook secret all belong on the server. Renew the access token when it expires rather than storing it long-term.
Conclusion
Monerium's webhooks track the orders that move euros between IBANs and blockchains, signed with a secret you generate and activated by a subscription.created handshake. Deploy before you register, answer that first event with 200, settle only on processed, deduplicate on webhook-id, and reconcile after any outage longer than Monerium's 12 hours of retries.
Hookdeck Event Gateway handles activation and storage for you, and keeps order events safe through longer outages. Sign up and register a Hookdeck source with Monerium's sandbox.