---
title: "Create a webhook"
method: POST
path: "/v2/webhooks"
tags: ["Webhooks API"]
---

# Create a webhook

`POST /v2/webhooks`

A webhook must have a name, an url and a list of event types. You can also create webhooks in the webhooks settings section of the Dashboard.

## Headers

- `idempotency-key` string

## Request body

- object
  - `name` string, required — A name that identifies the webhook.
  - `url` string, required — The URL Mollie will send the events to. This URL must be publicly accessible.
  - `eventTypes` union, required
    - WebhookEventTypes[] — The list of events to enable for this webhook. You may specify `'*'` to add all events, except those that require explicit selection.
    - 'payment.paid' | 'payment.authorized' | 'payment.failed' | 'payment.canceled' | 'payment.expired' | 'payment.pending' | 'refund.queued' | 'refund.pending' | 'refund.processing' | 'refund.refunded' | 'refund.failed' | 'refund.canceled' | 'chargeback.received' | 'chargeback.reversed' | 'capture.succeeded' | 'capture.failed' | 'payment-link.paid' | 'balance-transaction.created' | 'payout.initiated' | 'payout.processing-at-bank' | 'payout.completed' | 'payout.canceled' | 'payout.failed' | 'sales-invoice.created' | 'sales-invoice.issued' | 'sales-invoice.canceled' | 'sales-invoice.paid' | 'sales-invoice.e-invoice-failed' | 'sales-invoice.e-invoice-issued' | 'business-account-transfer.requested' | 'business-account-transfer.initiated' | 'business-account-transfer.pending-review' | 'business-account-transfer.processed' | 'business-account-transfer.failed' | 'business-account-transfer.blocked' | 'business-account-transfer.returned' | '*' — The list of events to enable for this webhook. You may specify `'*'` to add all events, except those that require explicit selection.
  - `testmode` boolean — Whether to create the entity in test mode or live mode. You can enable test mode by setting `testmode` to `true`.

## Response `201`

The webhook object.

## Other responses

- `422` — The request contains issues. For example, if the URL is missing.
- `429` — Rate Limit has been reached.

## Changes

> 79 revisions in range; 9 not diffed.

- **2026-07-02** `e8c8cac71380` — 4 warning, 8 info
  - added the new `capture.failed` enum value to the `eventTypes/items/` response property for the response status `201`
  - added the new `capture.succeeded` enum value to the `eventTypes/items/` response property for the response status `201`
  - added the new `chargeback.received` enum value to the `eventTypes/items/` response property for the response status `201`
  - added the new `chargeback.reversed` enum value to the `eventTypes/items/` response property for the response status `201`
  - …8 more
- **2026-06-22** `19c365c4aee4` — 2 warning, 4 info
  - added the new `sales-invoice.e-invoice-failed` enum value to the `eventTypes/items/` response property for the response status `201`
  - added the new `sales-invoice.e-invoice-issued` enum value to the `eventTypes/items/` response property for the response status `201`
  - added the new `sales-invoice.e-invoice-failed` enum value to the request property `eventTypes/oneOf[#/components/schemas/webhook-event-types]/`
  - added the new `sales-invoice.e-invoice-failed` enum value to the request property `eventTypes/oneOf[subschema #1]/items/`
  - …2 more
- **2026-05-19** `7cab62b21830` — 1 info
  - added the non-success response with the status `429`
- …earlier changes not shown

[Full history](https://skmtc.dev/mollie/apis/mollie-api/changes/v2/webhooks/post.md)

---

[API](https://skmtc.dev/mollie/apis/mollie-api.md) · [All operations](https://skmtc.dev/mollie/apis/mollie-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/mollie/mollie-api/revisions/b7497b77b18f/schema)