Agent skill
Monerium Webhooks Skill
Receive and verify Monerium webhooks, which follow the Standard Webhooks specification. Use when registering a Monerium webhook with POST /webhooks, generating the whsec_ secret, debugging webhook-id / webhook-timestamp / webhook-signature verification, or handling order.created, order.updated and subscription.created events for EURe orders.
Install this skill
npx skills add hookdeck/webhook-skills --skill monerium-webhooks
Monerium 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.createdandorder.updatedevents, or react to aprocessedorrejectedorder? - 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.
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):
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, 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/, examples/nextjs/, 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:
{
"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.
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
MONERIUM_WEBHOOK_SECRET=whsec_xxxxx # the full value you generated and sent to Monerium; handlers fail closed (500) without it
Local Development
# 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.
Reference Materials
- references/overview.md - Event catalog, envelope and payload fields
- references/setup.md - Authenticate, generate the secret, register and activate the webhook
- references/verification.md - Library and manual verification, gotchas, debugging