Mollie webhooks
Last verified against Mollie's documentation on September 27, 2026.
Mollie’s classic webhooks are as thin as webhooks get: a form POST with a single field, the ID of the payment or order that changed. There’s no status and no signature. Your handler fetches the object from Mollie’s API, and that fetch is what makes it trustworthy. Mollie retries 10 times over 26 hours until it gets a 200. Its newer next-gen webhooks add event types and a signature. This page covers both, how to fix the common errors, and where HookDeploy fits.
What Mollie sends webhooks for
Classic webhooks fire when a payment, order, refund, or subscription changes. The body is form-encoded with one field:
id=tr_d0b0E3EA3v
Fetch the object with that ID from the API to see what changed, for example whether the payment is now paid, failed, expired, or canceled.
Next-gen webhooks send an event object describing which entity changed and how, and sign it with an X-Mollie-Signature header.
How Mollie delivers webhooks
| Behavior | Detail |
|---|---|
| Classic format | POST, application/x-www-form-urlencoded, with a single id field |
| Classic security | No signature. Fetch the object from the API with your API key |
| Next-gen signature | X-Mollie-Signature: sha256=<hex>, an HMAC-SHA256 of the raw body with your signing secret |
| Timeout | 15 seconds |
| Success | 200 |
| Retries | 10 attempts over about 26 hours |
| Next-gen failures | A webhook that keeps failing over 24 hours is marked blocked until you reactivate it |
| Source IPs | Not fixed. Mollie advises against IP allowlisting |
Common Mollie webhook errors and how to fix them
Treating the webhook as the status
Classic webhooks don’t include a status, and anyone can post a fake ID. Always fetch the object from Mollie’s API and act on what it returns. A forged ID can only make you re-fetch a real payment.
Paid orders stuck as pending
If your handler returns 200 even when its API call to Mollie fails, Mollie stops retrying and the order never updates. Return a non-200, such as 503, when you couldn’t fetch the status, and 200 for IDs you don’t recognize.
Webhook never arrives locally
Mollie can’t reach localhost. Pass a public webhook URL when you create the payment, or set one on the profile.
Next-gen signature fails
Strip the sha256= prefix, hash the raw body, and use the signing secret from the webhook’s settings.
Why use HookDeploy with Mollie
Capture every call
HookDeploy captures every Mollie webhook at Cloudflare’s edge and responds right away, before forwarding it to your server. If your handler can’t reach Mollie’s API, it can return an error to HookDeploy, and HookDeploy retries it, without relying on Mollie’s retry window.
- Destination retries. Starter retries 3 times (after 30 seconds, 5 minutes, and 30 minutes). Pro and Scale retry up to 5 times on a schedule you choose. Free doesn’t retry automatically.
- Incidents. Forward failures are grouped into incidents, and you can bulk-replay them once your server recovers.
- History. HookDeploy keeps captured webhooks for your plan’s retention period, from 7 days on Free to 365 days on Enterprise.
One webhook, many systems
Send each Mollie event to your app, your accounting or ERP system, and an alert channel in parallel. A failing destination doesn’t hold up the others. Free includes 1 destination per endpoint, Starter includes 5, and Pro and above are unlimited.
Deliver to systems Mollie can’t reach
The HookDeploy Agent connects outward from your network over mTLS and delivers events to a local port, so a billing or fulfillment service in a private network can receive Mollie events with no public endpoint.
Develop against real events
A tap sends a temporary copy of live Mollie events to 127.0.0.1 on your machine while production keeps receiving them.
Know the limits
- Your handler’s errors stay with HookDeploy. HookDeploy has already answered Mollie with a
200, so a503from your handler is a failed forward in HookDeploy, retried on your destination’s schedule. Use destination retries on paid plans, or replay from an incident. - Plan limits. On Free, requests beyond the monthly allowance or the daily limit get a
429, which Mollie treats as a failed delivery. Paid plans keep accepting traffic past the included volume.
Retries, replays, and duplicates
Classic webhooks carry only an ID, so a retry or replay is always safe: your handler fetches the current state again. Next-gen signatures cover only the body, with no timestamp, and HookDeploy forwards the body and X-Mollie-Signature header unchanged, so retries and replays verify like the original delivery.
The same ID can arrive several times. Make the handler’s updates idempotent by comparing the fetched status with what you’ve stored.
Set up Mollie with HookDeploy
- In HookDeploy, create an endpoint (for example,
Mollie live) and copy its URL. - On the Forwarding tab, add a destination pointing to your handler, or to an agent for private delivery, and set its retries.
- Use your HookDeploy URL as the
webhookUrlwhen you create payments, or set it as the profile’s webhook in the Mollie Dashboard. For next-gen webhooks, create the webhook under Developers, then Webhooks, and copy its signing secret. - Create a test payment, complete it in Mollie’s test checkout, and confirm the call appears in HookDeploy and reaches your handler.
Example handler (Node.js and Express)
import express from 'express';
import { createMollieClient } from '@mollie/api-client';
const app = express();
const mollie = createMollieClient({ apiKey: process.env.MOLLIE_API_KEY });
app.post('/webhooks/mollie', express.urlencoded({ extended: false }), async (req, res) => {
const id = req.body.id;
if (!id?.startsWith('tr_')) return res.sendStatus(200); // not a payment we handle
let payment;
try {
payment = await mollie.payments.get(id); // the fetch is the verification
} catch (err) {
if (err.statusCode === 404) return res.sendStatus(200); // unknown ID: acknowledge
return res.sendStatus(503); // couldn't fetch: ask for a retry
}
res.sendStatus(200);
await enqueue({ paymentId: payment.id, status: payment.status });
// Apply the status idempotently: skip it if you've already recorded it.
});
FAQ
Why does the Mollie webhook only contain an ID?
By design. The webhook tells you something changed, and you fetch the object from Mollie's API to see what. Since the API response is authoritative, a forged webhook can only make you re-fetch a real payment.
Are Mollie webhooks signed?
Classic webhooks aren't. Next-gen webhooks are, with an X-Mollie-Signature header containing an HMAC-SHA256 of the raw body, prefixed with sha256=.
How many times does Mollie retry a webhook?
10 times over about 26 hours, until it gets a 200 within 15 seconds. Next-gen webhooks that keep failing over 24 hours are marked blocked until you reactivate them.
What should my Mollie handler return if the API call fails?
A non-200 status, so the webhook is retried. Returning 200 when you couldn't fetch the status tells Mollie you're done, and the payment never updates.
Can I allowlist Mollie's IP addresses?
Mollie advises against it, since its sending addresses change. The classic model is secure because you fetch the object from the API yourself.
How does HookDeploy work with Mollie's fetch-to-confirm model?
HookDeploy captures each call and forwards the ID to your handler. If your handler can't reach Mollie's API, it returns an error to HookDeploy, which retries or lets you replay it later, with the same ID.