↔️Understanding notification
This page is intended to introduce webhook notifications. This feature is available in your 4P Finance account's API and lets you view the POST requests that 4P Finance sends to the return URL defined by the integrator. This POST contains only one piece of information: a notification token.
Additional information about setting up the notification URL and the mechanics involved in querying the details of a notification can be found on the Retrieving notification data page.
Just because the POST is sent successfully (200) to your return URL does not, by itself, mean the flow has completed fully. When you receive the POST, you'll need to query that notification's information.
Warning! The POST that 4P Finance sends to your return URL does not contain the transaction data, only the notification token. All information about that transaction will be returned once you consume the GET /notification/:token endpoint.
The notification process works as a "two-way street" — a POST request is made to your return URL once the Pix payment is confirmed, and then your system, holding the notification token, sends a request to consume the GET /pix/notification/:token endpoint, where :token is the notification token contained in the POST that was sent.
The flow follows this order:
4P Finance will send an HTTP POST request to the callback URL (webhook) provided when the transaction was created.
This notification is triggered automatically after:
On-ramp:
Payment confirmation; and
Confirmation that the cryptocurrency has been sent on the blockchain.
Off-ramp:
Confirmation that the cryptocurrency has been received.
The POST will contain only a notification token, allowing your system to validate and process the operation's final status securely and automatically.
As soon as you receive the POST request, make a GET request to the /notification/:token route, where :token will be the notification token we sent you.
By making new GET requests to /notification/:token, you'll receive updates about the transaction whenever there's a change, such as in the status: pending, processing, success or error.
Important! If your system queries the token we sent, we consider the notification to have been successfully delivered. If it isn't queried, we will keep retrying for up to 5 days.
In other words, if there's a request to the GET /notification/:token endpoint, we understand that you received the POST with the notification token and queried it, receiving in the response all the informational data about the transaction's confirmation.
Security
To ensure secure communication between servers, your callback (webhook) URL is required to use the HTTPS protocol.
Notifications are sent from the following outbound IPs:
44.196.63.157
We recommend configuring your infrastructure to accept requests only from this IP (allowlist), ensuring that only our servers can access your endpoint.
We strongly recommend that your system:
Generate a unique token per transaction on your backend;
Include that token as a parameter in the notification URL (
notification_url) when the transaction is created;Use that token to validate the authenticity of notifications received via POST;
Validate that the request originated from the specified IP.
This way, when receiving a notification from 4P Finance, your system will be able to:
Confirm that the request originated from our servers;
Validate the token received and ensure that the request corresponds exactly to the expected transaction.
Example webhook URL (notification_url):
https://webhook.mycompany.com/pix/?custom_id=12345&your-token=eae1fe563265167f8d88aec8cd4a7609