Skip to main content

​
What are webhooks?

Webhooks are HTTP POST notifications that the platform sends to your endpoint when a selected payment or cancellation event occurs. They let you react to changes without polling the API. You can manage webhooks under Settings → Webhooks.

​
New Webhooks experience

The new Webhooks experience is enabled per tenant. You need the appropriate webhook role to access the page:
  • webhook-viewer can view webhooks and delivery history.
  • webhook-editor can create, edit, pause, resume, and delete webhooks, and retry or resend deliveries.
Users with the webhook-editor role can see the current webhook count and tenant limit. The New webhook button is unavailable when the tenant reaches the limit.

​
Webhooks list

The new list displays each webhook as a card with:
  • Name and enabled or paused status
  • Endpoint URL
  • Type: Payments or Cancellations
  • Direction: Inbound, Outbound, or both
  • Payment scheme selection
Select a webhook to open its details. Existing webhooks can be edited from the details page. Webhooks list showing webhook names, statuses, types, directions, and schemes

​
Create a webhook

Select New webhook to open the three-step editor. You must select at least one event, one direction, and one payment scheme before you can save.

​
Step 1: Events

The Events step lets you choose the notifications that the webhook receives.
  • Use the Payments and Cancellations tabs to switch between event entities.
  • Payment events are grouped by resource, such as payment, payment_return, payment_cancellation, csm_fees, reverse_payment, or adjustment.
  • Cancellation events are grouped under cancellation.
  • Use the search box to find an event by its name or description.
  • Select individual events or select all events currently visible in the search results.
  • The counter on each tab shows how many events are selected.
A webhook cannot combine payment and cancellation events. For payment events, select the same status set for each selected payment resource. If you need different status sets, create separate webhooks. Events step showing payment resources, event counts, search, and event selection

​
Step 2: Filtering

The Filtering step controls which payment or cancellation records can produce the selected events.
  • Direction - select Outbound, Inbound, or both.
  • Payment scheme - select one or more schemes available for your tenant: SEPA, INST, SDD, SWIFT, or T2.
  • Restrict to accounts (IBAN range) - optionally add one or more IBAN patterns.
IBAN patterns are normalized to uppercase and stored without spaces. Use * as a wildcard. The pattern and the matching IBAN must have the same length. For example:
matches an IBAN with the same length and fixed characters in the positions shown. You can add multiple account patterns. Each pattern must be completed before you can add another one. Filtering step showing direction, payment scheme, and IBAN pattern options

​
Step 3: Endpoint

The Endpoint step contains the delivery settings:
  • Name - generated automatically for a new webhook, but editable. You can regenerate the suggested name before saving.
  • Endpoint URL - a publicly reachable HTTPS URL that receives the webhook. Private, localhost, and internal cluster URLs are not accepted.
  • Payload fields - choose which fields appear in the request body. The available fields depend on whether the selected events are payment or cancellation events.
  • Custom headers - add name/value pairs to send with each request. Authorization header values are masked in the UI.
  • Request preview - review the endpoint, built-in headers, custom headers, and example JSON payload before saving.
The preview includes the request ID, delivery ID, and signature header used by the platform. See Signature verification for how to verify webhook signatures.

​
Custom headers for authentication

Custom headers are configured per webhook and are sent with every delivery to that webhook’s endpoint. Use them to provide additional authentication or security context for your receiving service, for example:
  • An Authorization header containing a token or credential.
  • An API key header required by your gateway.
  • A tenant or integration identifier used to route or validate requests.
Add each header’s name and value in the Custom headers section. The request preview shows the configured headers; Authorization values are masked. Custom headers supplement the platform’s built-in request ID, delivery ID, and signature headers. They do not replace signature verification. You can configure up to 20 custom headers, with values up to 4,096 characters each. You cannot override platform-managed headers such as Content-Type, Host, X-Request-ID, X-Webhook-Delivery-ID, or finventi-signature-* headers. Select Create Webhook to save the new webhook. New webhooks are enabled by default. Endpoint step showing the generated name, endpoint URL, payload fields, custom headers, and request preview

​
Edit a webhook

Open a webhook and select Edit. The editor uses the same Events, Filtering, and Endpoint sections as the creation flow. When editing, you can:
  • Switch the webhook between Enabled and Paused.
  • Change selected events, filters, endpoint URL, payload fields, and custom headers.
  • Review the request preview with the current configuration.
  • Delete the webhook.
Deleting a webhook stops new deliveries and pending retries for it. Existing delivery history is retained.

​
Delivery history

When the new Webhooks experience is enabled, a webhook’s details page includes a Deliveries tab. The delivery history view shows deliveries for the selected webhook and lets you:
  • Filter by date, outcome, event, and resource ID.
  • Inspect the event, resource ID, delivery status, HTTP response, response body, request payload, and attempt history.
  • Open delivery details beside the table on larger screens or in a drawer on smaller screens.
  • Refresh the results and paginate through deliveries.
  • Retry failed deliveries or resend delivered deliveries when you have the webhook-editor role.
  • Select multiple available deliveries and retry or resend them in bulk.
Use the request ID, event name, and resource ID when investigating a specific notification.

​
Retry and resend deliveries

Use the delivery details action to resend an individual delivery, or select multiple available deliveries and use the bulk action:
  • Retry a failed or blocked delivery to send the notification again.
  • Resend a delivered notification when your service needs to receive it again.
These actions create a new delivery attempt using the webhook’s current endpoint configuration, including its custom headers. The delivery details show the attempt count, latest response or error, next retry time when one is scheduled, and the complete attempt history. Only users with the webhook-editor role can retry or resend deliveries, and the action is shown only when it is available for the selected delivery. If an attempt fails, the delivery can remain Retry scheduled while an automatic retry is pending. During an automatic retry attempt, you cannot start a manual retry or resend for the same delivery. Wait until the automatic attempt finishes, then use the manual action when it becomes available. Use the Next retry value in the delivery details to see when a scheduled retry is expected. Automatic retries use exponential backoff within a three-day window measured from the original delivery creation time:
  • The first retry is scheduled one minute after the failed attempt.
  • Each subsequent failed attempt doubles the delay: two minutes, four minutes, eight minutes, and so on.
  • No retry is scheduled if the next attempt would fall outside the three-day window. The delivery then remains blocked until you retry or resend it manually, if the action is available.
The retry worker checks for due deliveries every minute by default. Because it runs on a schedule, an automatic retry can start shortly after its scheduled Next retry time rather than exactly at that time. Webhook delivery history showing delivery filters, statuses, response details, request payload, and attempt history Delivery details showing the Resend action after an automatic retry attempt has finished

​
Best practices

  • Use a publicly reachable HTTPS endpoint.
  • Make your endpoint idempotent because a notification can be retried or resent.
  • Return a successful 2xx response as soon as possible and process heavy work asynchronously.
  • Start with only the events and payload fields your integration needs.
  • Add custom headers only when your endpoint requires them.
  • Use the request preview to verify the URL, headers, and payload shape before saving.

​
Troubleshooting

  • The New webhook button is disabled. You may not have the webhook-editor role, or your tenant may have reached its webhook limit.
  • You cannot save the webhook. Select at least one event, direction, and payment scheme, complete all IBAN patterns, and use a publicly reachable HTTPS URL.
  • An event is missing. Use the search box, switch between Payments and Cancellations, or ask support whether the event is available for your tenant.
  • A delivery failed. Open the delivery details to inspect the response and attempt history, then retry it after correcting the endpoint.
Last modified on October 21, 2026