Instant Payment Notifications (IPN) Integration Guide

Introduction to Webhook Integration

Webhooks are an essential tool for automating real-time notifications and enabling seamless integrations with external systems. At UniPayment, we provide robust webhook support to help you stay informed about key business events as they happen, directly within your systems. Our webhooks can deliver instant notifications on the status of invoices, deposits, payments, and currency exchanges, allowing you to respond quickly to any changes.

Configuring Webhook Notifications

UniPayment allows you to set webhook notification URLs (notify_url) based on the type of transaction. For deposits, payments, and currency exchanges, the notify_url is fixed system-wide.

Configuring Global Notify URL and Secret Key

In this section, you will set the global notify_url, which is responsible for receiving notifications for deposits, payments, and currency exchanges. The secret key is crucial for verifying the authenticity of these notifications and is also used for verifying invoice notifications, ensuring secure communication across all transaction types.

For invoices, you have more flexibility. You can set a notify_url at the payment app level, applying to all invoices from that app, or assign a unique URL to each individual invoice, giving you more control over how notifications are handled.

Method 1: Setting the Payment App Notify URL

Method 1 allows you to set a notify URL at the payment app level. This ensures that all invoices generated by the app will send notifications to the specified endpoint, simplifying the management of webhook notifications for multiple invoices.

Method 2: Setting a Custom Notify URL for Individual Invoices
As an alternative method, you can assign different notify URLs for each invoice. This approach allows greater flexibility in managing notifications for specific transactions, ensuring that each invoice directs notifications to the appropriate endpoint.

Testing Webhook Notifications

You can use webhook.site, a handy tool for debugging, to inspect incoming notifications without setting up your own server.

To test:

Go to webhook.site and copy the unique URL provided.
Set this URL as your notify_url in the UniPayment console.
Trigger a transaction (such as an invoice) to generate a notification.
View the notification payload on webhook.site to verify that your system is receiving the expected data.

This method allows you to ensure your notifications are correctly configured before integrating with your production environment.

Each business type has a specific set of statuses and fields.

For Invoice status and field definitions, visit: Invoice Notification
For Payment status and field definitions, visit: Payment Notification
For Exchange status and field definitions, visit: Exchange Notification

Verifying Webhook Notifications

The security of our Webhook notifications is paramount, which is why each notification includes a signature in the header to ensure its integrity and authenticity. This signature is calculated using HMAC_SHA256, providing a reliable method to verify the source and integrity of the message.

How the Signature Algorithm Works

Webhook notifications are secured by encoding the JSON payload using UTF-8 and hashing it with HMAC-SHA256 along with a shared secret key. The resulting hash is then encoded in Base64 to generate the signature. This signature is included in the notification header under the key hmac_signature.

Example Header:

hmac_signature: 009WvyrcCu7XjZGiSS7I7ZSXlEYdVCM/Uz/h41obZTE=

Algorithm Examples for Different Languages

To help with implementation, we've provided links to code examples in various programming languages for verifying the HMAC signature:

Python: Python HMAC Signature Example
Node.js: Node.js HMAC Signature Example
Java: Java HMAC Signature Example
PHP: PHP HMAC Signature Example

Verifying the Signature

To verify the authenticity of a received notification:

Retrieve the hmac_signature from the header of the webhook notification.
Using the same payload (JSON body) and the shared secret key used during the configuration of your webhook, compute the HMAC hash using the HMAC_SHA256 algorithm.
Compare the Base64-encoded result of your computation with the hmac_signature from the webhook notification.

Online Verification Using HMAC Signature Tool

You can also use an online tool like the HMAC Signature Online Tool to quickly verify the signature. Here’s how:

Paste the Raw Content into [Enter Plain Text to Compute Hash].
Enter your secret key into [Enter the Secret Key].
Select SHA-256 as the hash algorithm.
Chose Base64 as Output Text Format.
Compute the hash and compare it with the hmac_signature value from the webhook header.

Important Considerations for Verifying HMAC Signature

When verifying webhook notifications, it is essential to correctly retrieve the hmac_signature from the request headers. In some cases, headers might be altered or transformed, especially when passing through proxies or intermediate services. As shown in the code snippet, it's necessary to account for variations in the header name:

$hmac_signature = '';
if (array_key_exists('hmac-signature', $header)) $hmac_signature = $header['hmac-signature'];
if (array_key_exists('Hmac-Signature', $header)) $hmac_signature = $header['Hmac-Signature'];
if (array_key_exists('HMAC-SIGNATURE', $header)) $hmac_signature = $header['HMAC-SIGNATURE'];

Things to Keep in Mind:

Header Name Variations: When receiving webhook requests, proxies or load balancers may alter the header's case or format. Ensure your code checks for all possible variations of the hmac-signature key (lowercase, camelCase, and uppercase).
Check Header Integrity: If you're unable to retrieve the hmac_signature, double-check your headers to ensure they have not been modified by intermediaries like proxies. Some services might strip or rename headers, which can cause issues during verification.
Proxy and Security: Always ensure that your headers arrive intact when passing through a proxy. It might be necessary to configure your proxy or API gateway to preserve header formatting to ensure the hmac_signature is passed correctly.

Following these steps will help you avoid issues related to signature verification, especially when routing webhook notifications through complex networks

Integrate with Payment Gateway

Node