# Monerium Webhooks

[Monerium](https://monerium.com) is an electronic money institution that issues euro e-money tokens (EURe) on-chain, with IBANs linked to wallets. Orders move money between IBANs and wallets, and order processing is asynchronous, so you register a webhook to hear about it. Deliveries follow Standard Webhooks: each carries `webhook-id`, `webhook-timestamp` and `webhook-signature` headers.

## When to Use This Skill

* How do I receive Monerium webhooks?
* How do I register a Monerium webhook (`POST /webhooks`) and what secret do I send?
* How do I verify a Monerium webhook signature (`webhook-signature`)?
* How do I handle `order.created` and `order.updated` events, or react to a `processed` or `rejected` order?
* Why does my Monerium webhook subscription stay inactive (`subscription.created`)?
* Why is my Monerium webhook verification failing, or failing only on retries and replays?

## You Create the Secret

Monerium does not issue a signing secret. You generate it, send it in the `secret` field of `POST /webhooks`, and keep the same value to verify deliveries. Hookdeck's configuration alert for this source says:

> 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.

```javascript
const secret = 'whsec_' + crypto.randomBytes(32).toString('base64');

```

## Verification (core)

| Header | Value |
| --- | --- |
| `webhook-id` | Identifies the message; retries reuse it. Your idempotency key |
| `webhook-timestamp` | Unix seconds |
| `webhook-signature` | One or more space-separated `v1,<base64>` entries |

Signed content is `{webhook-id}.{webhook-timestamp}.{raw body}`, HMAC-SHA256, base64 output. The key is the base64-**decoded** part of the `whsec_...` secret after the prefix. Compare against every `v1,` entry; ignore other versions. If `webhook-id` is absent, read `svix-id`, `svix-timestamp` and `svix-signature` instead. The examples use the `standardwebhooks` library (npm and PyPI):

```javascript
const { Webhook } = require('standardwebhooks');

// rawBody: exact request body (Buffer or string), NOT re-serialised JSON
function verifyMonerium(rawBody, headers, secret = process.env.MONERIUM_WEBHOOK_SECRET) {
  const p = headers['webhook-id'] ? 'webhook' : 'svix'; // fall back to the svix-* names
  new Webhook(secret).verify(rawBody, {
    'webhook-id': headers[`${p}-id`],
    'webhook-timestamp': headers[`${p}-timestamp`],
    'webhook-signature': headers[`${p}-signature`],
  }, { jsonParse: false }); // throws on a bad signature or stale timestamp → respond 401
}

```

The library always enforces a fixed **5-minute timestamp window**. Hookdeck retries and replays resend the original `webhook-timestamp`, so the library rejects them once they are more than 5 minutes old. If you receive through Hookdeck and need late retries to pass, use the manual verifier in [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/monerium-webhooks/references/verification.md), which can drop or widen the window. In Express, read the body with `express.raw({ type: '*/*' })` so any content type verifies, and parse JSON only after the check.

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/monerium-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/monerium-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/monerium-webhooks/examples/fastapi/).

## Event Type and Payload

Every body is a `{ type, data }` envelope. The event name is the dotted top-level `type`, and the order is in `data` (`id`, `state`, `meta`). Monerium's guide prints no payload example, so these fields come from its handler code:

```json
{
  "type": "order.updated",
  "data": { "id": "<order id>", "state": "processed", "meta": { "txHashes": ["0x..."] } }
}

```

For `order.updated`, act on `state` `processed` (`meta.txHashes` holds the on-chain transaction hashes) and `rejected` (`meta.rejectedReason` explains why). For `order.created`, `data.kind` of `issue` means an incoming payment was detected; the guide also reads `amount`, `currency`, `chain` and `counterpart`.

## Common Event Types

| Event | Fired when |
| --- | --- |
| `order.created` | An order is created, e.g. an incoming payment is detected, before it is processed |
| `order.updated` | An order changes state. The primary event: act on `processed` and `rejected` |
| `subscription.created` | Sent to your URL right after you register the webhook; answer `200 OK` to activate the subscription |

The docs list these three and may not be exhaustive, so acknowledge types you don't recognise. See [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/monerium-webhooks/references/overview.md).

## Delivery Semantics

Anything other than `200 OK` is retried up to 10 times over 12 hours with exponential backoff. Store processed `webhook-id` values and deduplicate on them. The docs give no timeout or ordering guarantee, so respond quickly and process asynchronously. Return `400` for missing headers and `401` for a bad signature. Profile approval is notified by email, not by webhook.

## Environment Variables

```bash
MONERIUM_WEBHOOK_SECRET=whsec_xxxxx   # the full value you generated and sent to Monerium; handlers fail closed (500) without it

```

## Local Development

```bash
# Express / Next.js (use 8000 for FastAPI). No install or account required.
npx hookdeck-cli listen 3000 monerium --path /webhooks/monerium

```

Register the printed URL with `POST /webhooks`, using the secret from `MONERIUM_WEBHOOK_SECRET`. See [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/monerium-webhooks/references/setup.md).

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/monerium-webhooks/references/overview.md) - Event catalog, envelope and payload fields
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/monerium-webhooks/references/setup.md) - Authenticate, generate the secret, register and activate the webhook
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/monerium-webhooks/references/verification.md) - Library and manual verification, gotchas, debugging