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

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

Verification (core)

HeaderValue
webhook-idIdentifies the message; retries reuse it. Your idempotency key
webhook-timestampUnix seconds
webhook-signatureOne 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

EventFired when
order.createdAn order is created, e.g. an incoming payment is detected, before it is processed
order.updatedAn order changes state. The primary event: act on processed and rejected
subscription.createdSent 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


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 16, 2026

View on GitHub →