# Guide to Monerium Webhooks: Features and Best Practices

[Monerium](https://monerium.com) 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](https://docs.monerium.com/private). 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](https://sandbox.monerium.dev) first, using a Private application's client ID and secret.

1. Generate your signing secret and keep it server-side as `MONERIUM_WEBHOOK_SECRET`:
  
  
  ```javascript
  import crypto from 'crypto';
  
  const secret = 'whsec_' + crypto.randomBytes(32).toString('base64');
  
  ```
  
  
2. Get an access token with the client-credentials grant. It expires after an hour:
  
  
  ```javascript
  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',
    }),
  });
  
  ```
  
  
3. Deploy your receiver, verifying with the secret from step 1, before you register. The activation event arrives immediately.
4. Register the webhook:
  
  
  ```javascript
  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'],
    }),
  });
  
  ```
  
  
5. Answer the `subscription.created` delivery with `200 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](/docs/cli) and register its URL:

```bash
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:

```javascript
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:

```javascript
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](/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.created` with `200` explicitly.

**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](/docs/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](/webhooks/guides/implement-webhook-idempotency).

### 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](https://hookdeck.com) handles activation and storage for you, and keeps order events safe through longer outages. [Sign up](https://dashboard.hookdeck.com/signup) and register a Hookdeck source with Monerium's sandbox.