mollie-webhooks

Mollie Webhooks

When to Use This Skill

• Setting up a Mollie webhook handler
• Understanding why Mollie webhooks have no signature to verify
• How do I confirm a Mollie payment status from a webhook?
• Handling payment status changes: paid, authorized, canceled, expired, failed
• Why does my Mollie webhook only contain an id?

How Mollie Webhooks Work (Read This First)

Mollie webhooks are not signed — there is no HMAC, no signature header, and no shared secret to verify. Instead of trusting the request, Mollie sends you a POST with a single application/x-www-form-urlencoded body parameter:

id=tr_5B8cwPMGnU6qLbRvo7qEZo

The status is deliberately not in the payload. You must not trust the request body — anyone could POST a fake id. Instead you fetch the resource from the Mollie API using your API key and read the authoritative status. This is the fetch-to-confirm pattern, and it is the security model: a forged webhook can only ever cause you to re-fetch a real payment you own.

Mollie ──POST id=tr_xxx──▶  your endpoint
                              │
                              ▼
                    GET /v2/payments/tr_xxx  (with your API key)
                              │
                              ▼
                    read payment.status → act → return 200

Verification (core) — fetch to confirm

There is no signature to check. The "verification" step is fetching the payment from Mollie's API. Authenticate with your API key as a Bearer token (test_… or live_…). Always return 200 quickly — even for an unknown or deleted id — so Mollie stops retrying.

Node (official SDK, @mollie/api-client):

const { createMollieClient } = require('@mollie/api-client');
const mollie = createMollieClient({ apiKey: process.env.MOLLIE_API_KEY });

// req.body.id came from the x-www-form-urlencoded webhook — do NOT trust it as status.
const payment = await mollie.payments.get(req.body.id); // 404 => unknown id, ack with 200
switch (payment.status) {                               // authoritative status from the API
  case 'paid': /* fulfill order */ break;
  case 'expired': case 'failed': case 'canceled': /* release order */ break;
}