mollie-webhooks

Name: mollie-webhooks
Author: hookdeck

80stars10forks

How to install mollie-webhooks?

hookdeck/webhook-skills/mollie-webhooks

$npx -y skills add hookdeck/webhook-skills --skill mollie-webhooks

Installs into the current project.

Summary

Receive and handle Mollie webhooks. Use when setting up Mollie webhook handlers, understanding why Mollie webhooks are not signed, or handling payment status changes like paid, expired, failed, canceled, or authorized. Teaches the fetch-to-confirm pattern: the webhook only sends

Files · 1

View on GitHub

SKILL.md

1	# Mollie Webhooks
2
3	## When to Use This Skill
4
5	- Setting up a Mollie webhook handler
6	- Understanding why Mollie webhooks have no signature to verify
7	- How do I confirm a Mollie payment status from a webhook?
8	- Handling payment status changes: `paid`, `authorized`, `canceled`, `expired`, `failed`
9	- Why does my Mollie webhook only contain an `id`?
10
11	## How Mollie Webhooks Work (Read This First)
12
13	Mollie webhooks are not signed — there is no HMAC, no signature header, and
14	no shared secret to verify. Instead of trusting the request, Mollie sends you a
15	POST with a single `application/x-www-form-urlencoded` body parameter:
16
17	```
18	id=tr_5B8cwPMGnU6qLbRvo7qEZo
19	```
20
21	The status is deliberately not in the payload. You **must not trust the
22	request body — anyone could POST a fake `id`. Instead you fetch the resource
23	from the Mollie API** using your API key and read the authoritative status. This
24	is the fetch-to-confirm pattern, and it is the security model: a forged
25	webhook can only ever cause you to re-fetch a real payment you own.
26
27	```
28	Mollie ──POST id=tr_xxx──▶ your endpoint
29	│
30	▼
31	GET /v2/payments/tr_xxx (with your API key)
32	│
33	▼
34	read payment.status → act → return 200
35	```
36
37	## Verification (core) — fetch to confirm
38
39	There is no signature to check. The "verification" step is fetching the payment
40	from Mollie's API. Authenticate with your API key as a Bearer token
41	(`test_…` or `live_…`). Always return 200 quickly — even for an unknown or
42	deleted `id` — so Mollie stops retrying.
43
44	Node (official SDK, `@mollie/api-client`):
45
46	```javascript
47	const { createMollieClient } = require('@mollie/api-client');
48	const mollie = createMollieClient({ apiKey: process.env.MOLLIE_API_KEY });
49
50	// req.body.id came from the x-www-form-urlencoded webhook — do NOT trust it as status.
51	const payment = await mollie.payments.get(req.body.id); // 404 => unknown id, ack with 200
52	switch (payment.status) { // authoritative status from the API
53	case 'paid': /* fulfill order */ break;
54	case 'expired': case 'failed': case 'canceled': /* release order */ break;
55	}
56	```
57
58	Python (manual fetch — Mollie's official SDK is Node/PHP, so use the REST API):
59
60	```python
61	async with httpx.AsyncClient() as client:
62	r = await client.get(
63	f"https://api.mollie.com/v2/payments/{payment_id}",
64	headers={"Authorization": f"Bearer {os.environ['MOLLIE_API_KEY']}"},
65	)
66	# r.status_code == 404 => unknown id, acknowledge with 200
67	payment = r.json() # authoritative status from the API
68	status = payment["status"] # 'paid' \| 'authorized' \| 'canceled' \| 'expired' \| 'failed' \| ...
69	```
70
71	> For complete handlers with route wiring, status dispatch, and tests, see:
72	> - [examples/express/](examples/express/)
73	> - [examples/nextjs/](examples/nextjs/)
74	> - [examples/fastapi/](examples/fastapi/)
75
76	## Common Payment Statuses
77
78	The webhook fires whenever a payment's status changes. Fetch the payment to read
79	which status it now has:
80
81	\| Status \| Meaning \|
82	\|--------\|---------\|
83	\| `open` \| Payment created, not yet paid \|
84	\| `pending` \| Payment started, awaiting completion (some methods) \|
85	\| `authorized` \| Amount reserved (two-step / pay-later methods) — capture to collect \|
86	\| `paid` \| Payment successful — safe to fulfill \|
87	\| `canceled` \| Customer or merchant canceled before completion \|
88	\| `expired` \| Payment was not completed in time \|
89	\| `failed` \| Payment attempt failed \|
90
91	The webhook `id` prefix tells you the resource type: `tr_` = payment. Refunds and
92	chargebacks reuse the payment's webhook, so re-fetch the payment (and its refunds)
93	on any call.
94
95	> For the full status reference, see [Mollie payment status changes](https://docs.mollie.com/docs/payment-status-changes).
96
97	## Environment Variables
98
99	```bash
100	MOLLIE_API_KEY=test_xxxxx # Mollie API key (test_… or live_…) from the dashboard
101	```
102
103	The same API key both creates payments (with a `webhookUrl`) and fetches them
104	in the webhook handler. There is no separate webhook secret.
105
106	## Local Development
107
108	```bash
109	# Start tunnel (no account needed) — forwards to your local handler
110	npx hookdeck-cli listen 3000 mollie --path /webhooks/mollie
111	```
112
113	Set the resulting public URL as the `webhookUrl` when you create a payment
114	(Mollie does not have a dashboard field for a global payments web

People who liked this also viewed

6 picks

Type

mollie-webhooks

80stars10forks

View on GitHub

How to install mollie-webhooks?

hookdeck/webhook-skills/mollie-webhooks

$npx -y skills add hookdeck/webhook-skills --skill mollie-webhooks

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Mollie Webhooks
2
3	## When to Use This Skill
4
5	- Setting up a Mollie webhook handler
6	- Understanding why Mollie webhooks have no signature to verify
7	- How do I confirm a Mollie payment status from a webhook?
8	- Handling payment status changes: `paid`, `authorized`, `canceled`, `expired`, `failed`
9	- Why does my Mollie webhook only contain an `id`?
10
11	## How Mollie Webhooks Work (Read This First)
12
13	Mollie webhooks are not signed — there is no HMAC, no signature header, and
14	no shared secret to verify. Instead of trusting the request, Mollie sends you a
15	POST with a single `application/x-www-form-urlencoded` body parameter:
16
17	```
18	id=tr_5B8cwPMGnU6qLbRvo7qEZo
19	```
20
21	The status is deliberately not in the payload. You **must not trust the
22	request body — anyone could POST a fake `id`. Instead you fetch the resource
23	from the Mollie API** using your API key and read the authoritative status. This
24	is the fetch-to-confirm pattern, and it is the security model: a forged
25	webhook can only ever cause you to re-fetch a real payment you own.
26
27	```
28	Mollie ──POST id=tr_xxx──▶ your endpoint
29	│
30	▼
31	GET /v2/payments/tr_xxx (with your API key)
32	│
33	▼
34	read payment.status → act → return 200
35	```
36
37	## Verification (core) — fetch to confirm
38
39	There is no signature to check. The "verification" step is fetching the payment
40	from Mollie's API. Authenticate with your API key as a Bearer token
41	(`test_…` or `live_…`). Always return 200 quickly — even for an unknown or
42	deleted `id` — so Mollie stops retrying.
43
44	Node (official SDK, `@mollie/api-client`):
45
46	```javascript
47	const { createMollieClient } = require('@mollie/api-client');
48	const mollie = createMollieClient({ apiKey: process.env.MOLLIE_API_KEY });
49
50	// req.body.id came from the x-www-form-urlencoded webhook — do NOT trust it as status.
51	const payment = await mollie.payments.get(req.body.id); // 404 => unknown id, ack with 200
52	switch (payment.status) { // authoritative status from the API
53	case 'paid': /* fulfill order */ break;
54	case 'expired': case 'failed': case 'canceled': /* release order */ break;
55	}
56	```
57
58	Python (manual fetch — Mollie's official SDK is Node/PHP, so use the REST API):
59
60	```python
61	async with httpx.AsyncClient() as client:
62	r = await client.get(
63	f"https://api.mollie.com/v2/payments/{payment_id}",
64	headers={"Authorization": f"Bearer {os.environ['MOLLIE_API_KEY']}"},
65	)
66	# r.status_code == 404 => unknown id, acknowledge with 200
67	payment = r.json() # authoritative status from the API
68	status = payment["status"] # 'paid' \| 'authorized' \| 'canceled' \| 'expired' \| 'failed' \| ...
69	```
70
71	> For complete handlers with route wiring, status dispatch, and tests, see:
72	> - [examples/express/](examples/express/)
73	> - [examples/nextjs/](examples/nextjs/)
74	> - [examples/fastapi/](examples/fastapi/)
75
76	## Common Payment Statuses
77
78	The webhook fires whenever a payment's status changes. Fetch the payment to read
79	which status it now has:
80
81	\| Status \| Meaning \|
82	\|--------\|---------\|
83	\| `open` \| Payment created, not yet paid \|
84	\| `pending` \| Payment started, awaiting completion (some methods) \|
85	\| `authorized` \| Amount reserved (two-step / pay-later methods) — capture to collect \|
86	\| `paid` \| Payment successful — safe to fulfill \|
87	\| `canceled` \| Customer or merchant canceled before completion \|
88	\| `expired` \| Payment was not completed in time \|
89	\| `failed` \| Payment attempt failed \|
90
91	The webhook `id` prefix tells you the resource type: `tr_` = payment. Refunds and
92	chargebacks reuse the payment's webhook, so re-fetch the payment (and its refunds)
93	on any call.
94
95	> For the full status reference, see [Mollie payment status changes](https://docs.mollie.com/docs/payment-status-changes).
96
97	## Environment Variables
98
99	```bash
100	MOLLIE_API_KEY=test_xxxxx # Mollie API key (test_… or live_…) from the dashboard
101	```
102
103	The same API key both creates payments (with a `webhookUrl`) and fetches them
104	in the webhook handler. There is no separate webhook secret.
105
106	## Local Development
107
108	```bash
109	# Start tunnel (no account needed) — forwards to your local handler
110	npx hookdeck-cli listen 3000 mollie --path /webhooks/mollie
111	```
112
113	Set the resulting public URL as the `webhookUrl` when you create a payment
114	(Mollie does not have a dashboard field for a global payments web

People who liked this also viewed

6 picks

Type