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

# Create a webhook

`POST /v2/webhooks`

## Request

- Base URL: `https://api.mollie.com`
- URL: `https://api.mollie.com/v2/webhooks`
- Auth: one of:
  - HTTP bearer
  - OAuth 2
    - Authorization code: `https://my.mollie.com/oauth2/authorize`
    - Token URL: `https://api.mollie.com/oauth2/tokens` scopes: `webhooks.write`

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.

> 🔑 Access with
>
> [Advanced access token with **webhooks.write**](/reference/authentication)
>
> [OAuth access with **webhooks.write**](/reference/authentication)

## 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
    - string[]: 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' | 'business-account-draft-transfer.created' | 'business-account-draft-transfer.approved' | 'business-account-draft-transfer.declined' | 'unmatched-credit-transfer.received' | 'unmatched-credit-transfer.matched' | 'unmatched-credit-transfer.returned' | 'unmatched-credit-transfer.expired' | 'unmatched-credit-transfer.match.completed' | 'unmatched-credit-transfer.match.failed' | 'unmatched-credit-transfer.return.completed' | 'unmatched-credit-transfer.return.failed' | '*': The list of events to enable for this webhook. You may specify `'*'` to add all events, except those that require explicit selection. Possible values: `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` `business-account-draft-transfer.created` `business-account-draft-transfer.approved` `business-account-draft-transfer.declined` `unmatched-credit-transfer.received` `unmatched-credit-transfer.matched` `unmatched-credit-transfer.returned` `unmatched-credit-transfer.expired` `unmatched-credit-transfer.match.completed` `unmatched-credit-transfer.match.failed` `unmatched-credit-transfer.return.completed` `unmatched-credit-transfer.return.failed` `*`
  - `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.

- object
  - `resource` string, required: Indicates the response contains a webhook subscription object. Will always contain the string `webhook` for this endpoint.
  - `id` string, required: The identifier uniquely referring to this subscription.
  - `url` string, required: The subscription's events destination.
  - `profileId` string, nullable, required: The identifier uniquely referring to the profile that created the subscription.
  - `createdAt` string, required: The subscription's date time of creation.
  - `name` string, required: The subscription's name.
  - `eventTypes` string[], required: The events types that are subscribed.
  - `status` string, required: The subscription's current status. Possible values: `enabled` `blocked` `disabled` `deleted`
  - `mode` string, required: Whether this entity was created in live mode or in test mode. Possible values: `live` `test`
  - `webhookSecret` string, required: The subscription's secret.
  - `_links` object, required: An object with several relevant URLs. Every URL object will contain an `href` and a `type` field.
    - `self` object, required: In v2 endpoints, URLs are commonly represented as objects with an `href` and `type` field.
      - `href` string, required: The actual URL string.
      - `type` string, required: The content type of the page or endpoint the URL points to.
    - `documentation` object, required: In v2 endpoints, URLs are commonly represented as objects with an `href` and `type` field.
      - `href` string, required: The actual URL string.
      - `type` string, required: The content type of the page or endpoint the URL points to.

## Other responses

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

---

[API](https://skmtc.dev/mollie/apis/mollie-connect.md) - [All operations](https://skmtc.dev/mollie/apis/mollie-connect/llms.txt) - [OpenAPI document](https://skmtc.dev/mollie/apis/mollie-connect/revisions/65271e79a786?raw)