> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mattildapayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

Webhooks allow you to receive notifications of events that occurred on our
platform. These notifications are delivered to an HTTPS endpoint
of your choice.

## Setup

We support multiple webhook URLs per instance. Webhooks can be configured
by administrators by heading to **Settings** -> **Integrations** ->
**Webhook subscriptions**. For each subscription, it's possible to listen to
the events for all merchant accounts in an instance, or to the events for one
merchant account.

## Legacy webhook subscriptions migration

Before the introduction of our **Webhook subscriptions** dashboard, webhook configuration was limited:

* One webhook per **merchant account**, configured in **Settings** → **Manage merchants**
* One hard-coded **instance-level** webhook, configurable via our support team

These legacy subscriptions will **remain active** for the time being. We are planning an automatic migration, but you can also migrate manually:

* **Merchant-level**: While this option has been removed from the dashboard, it may still be active via the API. To migrate, enable a new subscription in **Settings** → **Integrations** → **Webhook subscriptions**, then unset the legacy URL using the API or via support if needed.
* **Instance-level**: Contact support to have this migrated to the new system

## Webhook delivery behavior (legacy vs. new)

To avoid confusion during the migration period, here are key behaviors you should be aware of:

1. **Active legacy and new subscriptions will both receive events**\
   As long as both are active and point to **different URLs**, each will receive webhook deliveries.
2. **No duplicate deliveries to the same URL**\
   If both a legacy and a new subscription point to the **same URL**, our system includes **deduplication logic**, and only one delivery will go through. This prevents duplicate webhook events.
3. **Retries are subscription-specific**\
   If a webhook delivery fails, it will only be retried for the subscription that encountered the failure — even if other subscriptions (pointing to the same or different URLs) succeed.
4. **Migration will eventually disable legacy subscriptions**\
   Once automatic migration is complete, only the new subscription system will remain active.

## Supported features

* Multiple webhook subscriptions per merchant account
* Merchant account and instance-level webhook subscriptions
* Detailed [payloads](./payload) for transactions, payment methods, buyers, billing details, and most other transaction related events.
* Over 20 different webhook [events](./events).
* Basic authentication credentials (username/password)
* Automatic retries of undelivered events
* Webhook [signatures](./signatures) to verify authenticity.

## Upcoming features

* Event filtering per subscription
* Event log and replay capabilities