Introduction

Webhooks allow your platform to receive real-time notifications when specific events occur in our system. Instead of constantly polling the API, your backend can listen for webhook events to trigger automated workflows, such as updating a user’s status or confirming a transaction.

📘
A webhook is essentially an HTTP POST request sent to a URL you configure. Each webhook contains basic information about the event, including its type, the related platform, and the target object (user, account, mandate, payout, etc.).

Managing Webhooks in the Backoffice

👍
Each platform can have its own webhooks configuration, directly done from the Mipise Payment Services backoffice.

You can view the list of webhook events that were triggered on a platform.

Each row contains:

UUID - the unique identifier of the webhook

Date - when the webhook was created

Category - the event type (e.g. pay_out_created)

Target - the object linked to the event (e.g. User, PayOut, DirectDebitMandate)

Status - either Success or Failed

Actions - retry or reset

📘
A webhook is considered Success if your endpoint responds with a 200.
It is considered Failed if your endpoint returns an error.

You can configure webhooks subscriptions.

Select which event type to subscribe to and provide the URL where notifications should be sent (usually on your platform).

Retry or reset webhooks directly from the interface.

List of Available Events

Here are all possible events that can trigger a webhook:

account_validated - An account has been successfully validated.
direct_debit_failed - A direct debit attempt failed.
direct_debit_successful - A direct debit attempt succeeded.
pay_in_successful - A pay-in (money received) was successful.
pay_in_failed - A pay-in attempt failed.
pay_out_created - A pay-out request was created.
pay_out_failed - A pay-out attempt failed.
pay_out_successful - A pay-out was successfully processed.
pay_out_validated - A pay-out has been validated.
mandate_approved - A direct debit mandate was approved.
mandate_canceled - A direct debit mandate was canceled.
mandate_signed - A direct debit mandate was signed.
user_validated - A user has been validated.
user_dequalified - A user has been dequalified.
kyc_validated - A KYC (identity verification, via the documents endpoints) request has been validated.
kyc_rejected - A KYC request was rejected.

Webhook Payload

Every webhook POST request contains the following x-www-form-urlencoded body:

id=notification.uuid&
event_type=notification.event_type&
platform_id=notification.platform.uuid&
target_id=target.uuid&
target_type=target.class.name

💡
Note: In actual requests, the payload is sent as a single line of URL-encoded key-value pairs.

Fields Descriptions

id - Unique identifier of the webhook notification.

event_type - The type of event (from the list above).

platform_id - The UUID of the platform concerned.

target_id - The UUID of the target object.

target_type - The object type linked to the event (e.g. user, account, financial request, mandate).

👍
To retrieve more details about the target, use the target_id with the appropriate 'GET' endpoint in the API (e.g. if the target type is user, then use the "GET User Details" endpoint).
Minimal information is sent in the webhook body for security reasons.