> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finventi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhooks management
## What are webhooks?
Webhooks are automatic notifications that the platform sends to a URL of your choice whenever a specific event happens on your account - for example, when a payment status changes or a cancellation is processed. Instead of polling our API to check for updates, your system receives an HTTP request the moment something relevant happens.
You can configure webhooks under **Settings → Webhooks**.
***
## The Webhooks list
The main Webhooks page shows all webhooks you have configured. For each one, you can see:
* **ID** - unique identifier of the webhook (useful for support requests)
* **Name** - the label you gave it
* **Type** - the event the webhook listens to (e.g. *Payment Status Change*, *Cancellation Status Change*)
* **Direction** - whether it covers *Inbound*, *Outbound*, or both payment flows
* **Status** - *Enabled* or *Disabled*
* **URL** - the endpoint that will receive the notifications
To add a new webhook, click **New Webhook**. The configuration form will open on the right side of the screen.
***
## Creating a new webhook
The form is divided into four sections.
### 1. Basic information
* **Name** - a short, descriptive label (e.g. *Outbound payments → ERP*). It is only used internally to help you identify the webhook in the list.
* **Webhook URL** - the HTTPS endpoint where notifications will be sent. Make sure this endpoint is reachable from the internet and able to accept POST requests.
* **Webhook Type** - the event category the webhook should subscribe to. Currently supported types include *Payment Status Change* and *Cancellation Status Change*.
### 2. Payment direction & status
* **Payment direction** - choose *Inbound*, *Outbound*, or both. Only events matching the selected direction will trigger the webhook.
* **Status** - toggle between *Enabled* and *Disabled*. A disabled webhook is saved but will not send any notifications until you re-enable it. This is useful for maintenance windows or for preparing a webhook before activating it.
### 3. Rule (optional filtering)
Rules let you narrow down exactly which events should trigger the webhook. If you leave every field set to **ALL**, the webhook will fire for every event matching the type and direction.
* **Schema** - restrict to a specific payment schema.
* **Transaction status** - only notify when the transaction reaches a particular status (e.g. *Accepted*, *Rejected*, *Completed*).
* **Transaction types** - restrict to one or more transaction types.
* **IBAN range** - restrict to a specific IBAN or range of IBANs.
> **Note:** If no rule is configured, the webhook sends notifications for all events of the chosen type and direction.
### 4. Payload fields
Choose which fields are included in the notification payload sent to your URL. By default all fields are selected. Available fields include:
* Transaction ID
* End-to-End ID
* Type
* Direction
* Amount
* Currency
* Status
* Updated At
* Debtor IBAN
* Creditor IBAN
* Method
Uncheck any field you don't need - this lets you keep the payload minimal and avoid sending data that isn't relevant to your integration.
When you're done, click **Create Webhook**. To discard your changes, click **Cancel**.
***
## Editing or removing a webhook
Click any webhook in the list to open its details. From there you can update any of the fields above, switch its status between *Enabled* and *Disabled*, or delete it entirely. Changes take effect immediately.
***
## Best practices
* **Use HTTPS** for your webhook URLs to keep the payloads encrypted in transit.
* **Make your endpoint idempotent.** In rare cases the same event may be delivered more than once; your system should handle duplicates gracefully (e.g. by checking the *Transaction ID*).
* **Respond quickly.** Your endpoint should return a `2xx` response as soon as possible. Do any heavy processing asynchronously after acknowledging the request.
* **Start with rules set to ALL**, then narrow them down once you've confirmed your endpoint is receiving events correctly.
* **Use a disabled webhook as a staging step.** Create it disabled, verify the configuration, then enable it when you're ready to receive traffic.
* **Only request the fields you need** in the payload section to minimize data exposure on your side.
***
## Troubleshooting
* **Not receiving any events?** Check that the webhook is *Enabled*, that the URL is reachable from the public internet, and that the rule isn't filtering out everything you expect.
* **Receiving too many events?** Tighten the rule, for example, restrict by *Transaction status* or *IBAN range*.
* **Need to investigate a specific delivery?** Provide the webhook **ID** (visible in the list) to support along with the approximate timestamp.