# Create a webhook

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
>
> [Organization access token with **webhooks.write**](/reference/authentication)
>
> [OAuth access with **webhooks.write**](/reference/authentication)

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Mollie Connect",
    "version": "1.0.0",
    "license": {
      "name": "Attribution-NonCommercial-ShareAlike 4.0 International",
      "identifier": "CC-BY-NC-SA-4.0"
    }
  },
  "servers": [
    {
      "url": "https://api.mollie.com"
    }
  ],
  "security": [
    {
      "apiKey": []
    },
    {
      "organizationAccessToken": []
    },
    {
      "oAuth": []
    }
  ],
  "paths": {
    "/v2/webhooks": {
      "post": {
        "summary": "Create a webhook",
        "x-speakeasy-name-override": "create",
        "tags": [
          "Webhooks API"
        ],
        "operationId": "create-webhook",
        "security": [
          {
            "organizationAccessToken": [
              "webhooks.write"
            ]
          },
          {
            "oAuth": [
              "webhooks.write"
            ]
          }
        ],
        "description": "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.\n\n> 🔑 Access with\n>\n> [Organization access token with **webhooks.write**](/reference/authentication)\n>\n> [OAuth access with **webhooks.write**](/reference/authentication)",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "A name that identifies the webhook.",
                    "example": "Webhook #1"
                  },
                  "url": {
                    "type": "string",
                    "description": "The URL Mollie will send the events to. This URL must be publicly accessible.",
                    "example": "https://mollie.com/"
                  },
                  "eventTypes": {
                    "oneOf": [
                      {
                        "type": "array",
                        "description": "The list of events to enable for this webhook. You may specify `'*'` to add all events, except those that require explicit selection.",
                        "items": {
                          "type": "string",
                          "description": "The list of events to enable for this webhook. You may specify `'*'` to add all events, except those that require explicit selection.\n\nPossible values: `payment-link.paid` `balance-transaction.created` `sales-invoice.created` `sales-invoice.issued` `sales-invoice.canceled` `sales-invoice.paid` `*`",
                          "x-speakeasy-name-override": "webhook-event-types",
                          "x-enumDescriptions": {
                            "payment-link.paid": "Occurs when a payment link has been paid.",
                            "balance-transaction.created": "Occurs when a balance transaction is created to add to your available balance. It currently only supports positive amounts and non-captured payments.",
                            "sales-invoice.created": "Occurs when a sales invoice has been created.",
                            "sales-invoice.issued": "Occurs when a sales invoice has been issued.",
                            "sales-invoice.canceled": "Occurs when a sales invoice has been canceled.",
                            "sales-invoice.paid": "Occurs when a sales invoice has been paid.",
                            "*": "All event types."
                          },
                          "example": "payment-link.paid"
                        }
                      },
                      {
                        "type": "string",
                        "description": "The list of events to enable for this webhook. You may specify `'*'` to add all events, except those that require explicit selection.\n\nPossible values: `payment-link.paid` `balance-transaction.created` `sales-invoice.created` `sales-invoice.issued` `sales-invoice.canceled` `sales-invoice.paid` `*`",
                        "x-speakeasy-name-override": "webhook-event-types",
                        "x-enumDescriptions": {
                          "payment-link.paid": "Occurs when a payment link has been paid.",
                          "balance-transaction.created": "Occurs when a balance transaction is created to add to your available balance. It currently only supports positive amounts and non-captured payments.",
                          "sales-invoice.created": "Occurs when a sales invoice has been created.",
                          "sales-invoice.issued": "Occurs when a sales invoice has been issued.",
                          "sales-invoice.canceled": "Occurs when a sales invoice has been canceled.",
                          "sales-invoice.paid": "Occurs when a sales invoice has been paid.",
                          "*": "All event types."
                        },
                        "example": "payment-link.paid"
                      }
                    ]
                  },
                  "testmode": {
                    "type": "boolean",
                    "description": "Whether to create the entity in test mode or live mode.\n\nYou can enable test mode by setting `testmode` to `true`.",
                    "writeOnly": true,
                    "example": false
                  }
                },
                "required": [
                  "name",
                  "url",
                  "eventTypes"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The webhook object.",
            "content": {
              "application/hal+json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "resource",
                    "id",
                    "url",
                    "profileId",
                    "createdAt",
                    "name",
                    "eventTypes",
                    "status",
                    "mode",
                    "webhookSecret",
                    "_links"
                  ],
                  "properties": {
                    "resource": {
                      "type": "string",
                      "description": "Indicates the response contains a webhook subscription object. Will always contain the string `webhook` for this endpoint.",
                      "readOnly": true,
                      "example": "webhook"
                    },
                    "id": {
                      "type": "string",
                      "description": "The identifier uniquely referring to this subscription.",
                      "readOnly": true,
                      "example": "hook_tNP6fpF9fLJpFWziRcgiH"
                    },
                    "url": {
                      "type": "string",
                      "description": "The subscription's events destination.",
                      "example": "https://example.com/webhook-endpoint"
                    },
                    "profileId": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The identifier uniquely referring to the profile that created the subscription.",
                      "readOnly": true,
                      "example": "pfl_YyoaNFjtHc"
                    },
                    "createdAt": {
                      "type": "string",
                      "description": "The subscription's date time of creation.",
                      "readOnly": true,
                      "example": "2023-01-01T12:00:00+00:00"
                    },
                    "name": {
                      "type": "string",
                      "description": "The subscription's name.",
                      "example": "Profile Updates Webhook"
                    },
                    "eventTypes": {
                      "type": "array",
                      "items": {
                        "type": "string",
                        "description": "The list of events to enable for this webhook. You may specify `'*'` to add all events, except those that require explicit selection.\n\nPossible values: `payment-link.paid` `balance-transaction.created` `sales-invoice.created` `sales-invoice.issued` `sales-invoice.canceled` `sales-invoice.paid` `*`",
                        "x-speakeasy-name-override": "webhook-event-types",
                        "x-enumDescriptions": {
                          "payment-link.paid": "Occurs when a payment link has been paid.",
                          "balance-transaction.created": "Occurs when a balance transaction is created to add to your available balance. It currently only supports positive amounts and non-captured payments.",
                          "sales-invoice.created": "Occurs when a sales invoice has been created.",
                          "sales-invoice.issued": "Occurs when a sales invoice has been issued.",
                          "sales-invoice.canceled": "Occurs when a sales invoice has been canceled.",
                          "sales-invoice.paid": "Occurs when a sales invoice has been paid.",
                          "*": "All event types."
                        },
                        "example": "payment-link.paid"
                      },
                      "description": "The events types that are subscribed.",
                      "example": [
                        "sales-invoice.paid, sales-invoice.canceled"
                      ]
                    },
                    "status": {
                      "type": "string",
                      "description": "The subscription's current status.\n\nPossible values: `enabled` `blocked` `disabled` `deleted`",
                      "example": "enabled"
                    },
                    "mode": {
                      "type": "string",
                      "description": "Whether this entity was created in live mode or in test mode.\n\nPossible values: `live` `test`",
                      "readOnly": true,
                      "example": "live"
                    },
                    "webhookSecret": {
                      "type": "string",
                      "description": "The subscription's secret.",
                      "example": "secret"
                    },
                    "_links": {
                      "type": "object",
                      "description": "An object with several relevant URLs. Every URL object will contain an `href` and a `type` field.",
                      "required": [
                        "self",
                        "documentation"
                      ],
                      "properties": {
                        "self": {
                          "type": "object",
                          "description": "In v2 endpoints, URLs are commonly represented as objects with an `href` and `type` field.",
                          "required": [
                            "href",
                            "type"
                          ],
                          "properties": {
                            "href": {
                              "type": "string",
                              "description": "The actual URL string.",
                              "example": "https://..."
                            },
                            "type": {
                              "type": "string",
                              "description": "The content type of the page or endpoint the URL points to.",
                              "example": "application/hal+json"
                            }
                          }
                        },
                        "documentation": {
                          "type": "object",
                          "description": "In v2 endpoints, URLs are commonly represented as objects with an `href` and `type` field.",
                          "required": [
                            "href",
                            "type"
                          ],
                          "properties": {
                            "href": {
                              "type": "string",
                              "description": "The actual URL string.",
                              "example": "https://..."
                            },
                            "type": {
                              "type": "string",
                              "description": "The content type of the page or endpoint the URL points to.",
                              "example": "application/hal+json"
                            }
                          }
                        }
                      },
                      "readOnly": true
                    }
                  }
                },
                "examples": {
                  "create-webhook-200": {
                    "summary": "The webhook subscription object.",
                    "value": {
                      "resource": "webhook",
                      "id": "hook_B2EyhTH5N4KWUnoYPcgiH",
                      "url": "https://mollie.com",
                      "profileId": "pfl_8XcSdLtrNK",
                      "createdAt": "2024-12-06T10:09:56+00:00",
                      "name": "Webhook #1",
                      "status": "enabled",
                      "mode": "live",
                      "webhookSecret": "VpQ3WukU6uSCGQ8TPTD3WPDpac3GyNEj",
                      "eventTypes": [
                        "payment-link.paid"
                      ],
                      "_links": {
                        "self": {
                          "href": "...",
                          "type": "application/hal+json"
                        },
                        "documentation": {
                          "href": "https://docs.mollie.com/reference/create-webhook",
                          "type": "text/html"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "422": {
            "description": "The request contains issues. For example, if the URL is missing.",
            "content": {
              "application/hal+json": {
                "schema": {
                  "type": "object",
                  "description": "An error response object.",
                  "required": [
                    "status",
                    "title",
                    "detail",
                    "_links"
                  ],
                  "properties": {
                    "status": {
                      "type": "integer",
                      "description": "The status code of the error message. This is always the same code as the status code of the HTTP message itself.",
                      "minimum": 400,
                      "maximum": 599,
                      "example": 404
                    },
                    "title": {
                      "type": "string",
                      "description": "The HTTP reason phrase of the error. For example, for a `404` error, the `title` will be `Not Found`.",
                      "example": "Not Found"
                    },
                    "detail": {
                      "type": "string",
                      "description": "A detailed human-readable description of the error that occurred.",
                      "example": "The resource does not exist"
                    },
                    "field": {
                      "type": "string",
                      "description": "If the error was caused by a value provided by you in a specific field, the `field` property will contain the name of the field that caused the issue.",
                      "example": "description"
                    },
                    "_links": {
                      "type": "object",
                      "required": [
                        "documentation"
                      ],
                      "properties": {
                        "documentation": {
                          "type": "object",
                          "description": "The URL to the generic Mollie API error handling guide.",
                          "required": [
                            "href",
                            "type"
                          ],
                          "properties": {
                            "href": {
                              "type": "string",
                              "example": "https://docs.mollie.com/errors"
                            },
                            "type": {
                              "type": "string",
                              "example": "text/html"
                            }
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "status": 422,
                  "title": "Unprocessable entity",
                  "detail": "Invalid URL provided",
                  "field": "url",
                  "_links": {
                    "documentation": {
                      "href": "...",
                      "type": "text/html"
                    }
                  }
                }
              }
            }
          }
        },
        "x-readme": {
          "code-samples": [
            {
              "language": "shell",
              "code": "curl -X POST https://api.mollie.com/v2/webhooks \\\n    -H \"Authorization: Bearer access_UsJwq8nzcHbSrDuh82pyjjEaTbd5SAPtVebEJ5BH\" \\\n    -d \"name=Payment notification\" \\\n    -d \"url=https://mollie.com\" \\\n    -d \"eventTypes=payments.read\""
            },
            {
              "language": "php",
              "code": "<?php\nuse Mollie\\Api\\Http\\Requests\\CreateWebhookRequest;\nuse Mollie\\Api\\Types\\WebhookEventType;\n\n$mollie->setAccessToken('access_UsJwq8nzcHbSrDuh82pyjjEaTbd5SAPtVebEJ5BH');\n\n$webhook = $mollie->send(\n    new CreateWebhookRequest(\n        url: 'https://mollie.com',\n        name: 'Payment notification',\n        eventTypes: 'payments.read'\n    )\n);",
              "install": "composer require mollie/mollie-api-php"
            },
            {
              "language": "node",
              "code": "/*\nWe don't have a Node.js code example for this\nAPI call yet.\n\nIf you have some time to spare, feel free to\nshare suggestions on our Discord:\nhttps://discord.gg/VaTVkXB4aQ\n*/",
              "install": "npm install @mollie/api-client"
            },
            {
              "language": "python",
              "code": "'''\nWe don't have a Python code example for this\nAPI call yet.\n\nIf you have some time to spare, feel free to\nshare suggestions on our Discord:\nhttps://discord.gg/VaTVkXB4aQ\n'''",
              "install": "pip install mollie-api-python"
            },
            {
              "language": "ruby",
              "code": "# We don't have a Ruby code example for this\n# API call yet.\n#\n# If you have some time to spare, feel free to\n# share suggestions on our Discord:\n# https://discord.gg/VaTVkXB4aQ",
              "install": "gem install mollie-api-ruby"
            }
          ]
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "x-default": "live_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM"
      },
      "organizationAccessToken": {
        "type": "http",
        "scheme": "bearer",
        "x-default": "access_dHar4XY7LxsDOtmnkVtjNVWXLSlXsM"
      },
      "oAuth": {
        "type": "oauth2",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://my.mollie.com/oauth2/authorize",
            "tokenUrl": "https://api.mollie.com/oauth2/tokens",
            "scopes": {}
          }
        }
      }
    }
  },
  "x-readme": {
    "explorer-enabled": false,
    "samples-languages": [
      "shell",
      "php",
      "node",
      "python",
      "ruby"
    ]
  }
}
```