Webhooks are notifications (HTTP callbacks) delivered in real-time to a designated URL on your system. Notifications are triggered by specific events, such as payment completions, refunds, or updates to a transaction state. For any issues, reach out to the help@nomupay.com.
Webhook setup
Follow the steps below to successfully implement webhook notifications into your environment. Before you begin, ensure you have an active account with NomuPay.
-
1. Create a webhook endpoint
The endpoint is simply a location on a server that listens for incoming
POST
notifications from NomuPay. Review requirements below when setting up your endpoint. Please note the full server url as this will be needed when submitting a webhook request.-
HTTPS is required & TLS v1.2 or higher must be enforced. HTTP is allowed in test systems only.
-
A valid SSL certificate from a recognised CA must be in place. Self-signed certificates are not permitted.
-
A firewall must be able to accept notifications from an external notification server
Go to step 2 to register your endpoint.
-
-
2. Register your endpoint
To register your endpoint, raise a Webhook Request to our support team and include all information related to the webhook and configuration options from the listing below. Upon successful webhook setup with your notification preferences, the support team will provide a secret key back to you, used for decrypting notifications.
-
Requirement Details Merchant Name
Include the appropriate business name registered at NomuPay that this webhook relates to.
Environment
Please select either Test or Live mode for the webhook location. Please note, if Live mode is selected the endpoint must be HTTPS and cannot include HTTP only.
Endpoint URL
The public URL to receive the notifications.
Test URL (HTTP or HTTPS allowed)
Production URL (Only HTTPS allowed)
Notification Types
By default, the webhook will automatically subscribe to all notification types when activated.
Fields
The fields you want in the payload. Available options:
ALL The webhook payload includes all fields the transaction generates
NON_CUSTOMER_DATA The webhook payload includes only fields which are not customer data related
Wrapper
The wrapper for the content type of the encrypted payload. Ensure your server can handle the selected content type. Available Options:
None (Text/Plain) No wrapper for the webhook payload. Content-Type will be text/plain and the body will be an encrypted hexadecimal string.
JSON JSON wrapper for the webhook payload. Content-Type will be application/json and the body will be wrapped by JSON. Example: {"encryptedBody":"[(encrypted) hexadecimal string]"}
Emails
Email address for failure notifications. Merchant account owners must approve email notifications & recipient address.
-
-
3. Set up decryption keys
By default, the content of a notification is encrypted to protect data from fraud attempts. To decrypt these notifications, you'll need the implement the decryption key, provided by the NomuPay support team. Review the Decryption guidance to get started.
-
4. Consuming webhook notifications
Consuming webhooks involves receiving, parsing, and reacting to the JSON payloads delivered to your endpoint via
POST
requests. Review the webhook Structure & Types guidance for further information. Additionally, When your service receives a webhook notification, ensure it can return a 2xx HTTP status code. Otherwise, the webhook service considers the notification delivery as failed, and will retry sending the notification later according to the retry interval. -
5. Set up decryption keys
To start testing your webhook setup, contact our support team for webhook activation. Our support team will conduct a preliminary test by sending a webhook notification to your registered URL with simulated transaction data. A successful test is confirmed when your server appropriately responds with an HTTP 200 status code.
Following a successful preliminary test, our team will proceed to activate your webhook, enabling it to receive actual notifications. Real notifications will begin flowing as events corresponding to the webhook are triggered within our system.
Webhook Structure
Overview paragraph on webhook structure and types the audience will see in this section.
Property
typeRequired
Type of the notification sent. Specifies the context in which the notification is generated. |
actionConditional
Indicator of status change. This field is relevant only for
|
payloadRequired
Content of the notification in |
"type": [notification_type],
"action": [status],
"payload": [content]
Webhook Types
Overview paragraph on webhook structure and types the audience will see in this section.
Payment
when a payment is created or updated in the system. |
Registration
when a registration is created or deleted. |
Schedule
when a scheduler is created or deleted. |
Risk
when a risk transaction is created or updated. |
Availability
Review key information relating to webhook retries, availability and message queuing when planning and setting up your webhook environment.
-
Near real-time. What does near real-time mean?
-
If we don't receive a response within 30 seconds, the message is considered timed out. It will then be scheduled for retry. If we don't receive a HTTP status code 2xx response, the message is considered as failed. It will then be scheduled for retry.
-
The delivery of the notifications may fail reaching your URL destination. The failed notifications are stored for a limited period of time up to 30 days. They are retried at increasing time intervals until either the message is accepted or the maximum retry period is reached. After 30 days of retrying the failed notifications without success, the transactions can be looked up via the reporting endpoints or the user interface.
Retry-intervals:
- 1 minute
- 2 minutes
- 4 minutes
- 8 minutes
- 15 minutes
- 30 minutes
- 1 Hour
- every day until 30 days have passed since the first attempt.
-
When retrying the failed notifications at the next time interval, if they continue to timeout or fail then we fall into a failing retry pattern. Not all failed notification queued for your URL endpoint are attempted to be delivered. We stop retrying until the next retry interval. We reset the retry interval once we see all messages successfully delivered to your URL endpoint.
-
Every day you would receive an email summarizing the newest 100 failed notifications for the configured URL endpoint. The failed notifications queued for the last 30 days will be purged. You can still get transaction data by using the other platform reporting tools but your saved failed notifications will be lost.
-
There is no guarantee on the order of messages. If you first send request A and then request B, you might retrieve a notification first on B then on A, especially if:
- The time difference between the messages is smaller than the time it takes us to process them
- The receiving server was unavailable for that time. Once the server is up again new notifications will arrive in real time, old notifications however would only be resent once they are retried using the retry intervals specified above.
-
Especially in asynchronous workflows, it's possible to receive multiple messages for a final status. Please ensure that once a final rejected or successful transaction status notification is received, any other notifications updates for the same transaction are disregarded.
-
Please make sure that your server configured to receive notifications is able to properly handle the peak-loads that can be caused by the transaction processing on the entities you're listening to.
Security
To ensure the security of information and protect data from fraud attempts, webhook notifications are encrypted using UTF-8 to convert human-readable strings to hexadecimal format, so that only the intended recipient with the decryption key can access the original information; see the encryption details below for further understanding.
-
AES is a symmetric key encryption algorithm widely used for encrypting data.
AES-256
-
The key is a 64-character-long hexadecimal string unique to each webhook used to encrypt and decrypt notifications.
000102030405060708090A0B0C0D0E0F000102030405060708090A0B0C0D0E0F -
GCM is an operation mode for symmetric key cryptographic block ciphers, combining the Counter mode of encryption with Galois mode of authentication.
GCM
-
In GCM mode, padding is not required because the block cipher is turned into a stream cipher.
-
The IV is provided in the HTTP header as X-Initialization-Vector. It is a nonce (number used once) that ensures that each encryption operation is unique.
3D575574536D450F71AC76D8 -
Included in the HTTP header as X-Authentication-Tag, this tag is used to check the integrity and authenticity of the data.
19FDD068C6F383C173D3A906F7BD1D83 -
Both the payload and the IV are encoded in hexadecimal format.
{
Payload:
"{\"type\": \"PAYMENT\"}",
Payload in Hexadecimal (after getting bytes in UTF-8):
"7B2274797065223A20225041594D454E54227D",
Key in Hexadecimal:
"000102030405060708090A0B0C0D0E0F000102030405060708090A0B0C0D0E0F",
Initialization-Vector (Hexadecimal):
"3D575574536D450F71AC76D8",
Authentication-Tag (Hexadecimal):
"19FDD068C6F383C173D3A906F7BD1D83",
Encrypted value in Hexadecimal:
"F8E2F759E528CB69375E51DB2AF9B53734E393"
}
Decryption
Decryption is the process of converting this encrypted data back into its original form. It’s an essential step in webhook data handling because it allows the receiving system to interpret and utilize the data contained in the payload.
When a webhook event is triggered, the payload is encrypted using a specific encryption algorithm and a secret key. This encrypted payload is then sent to the specified URL. Upon receiving the payload, the server must decrypt it using the same algorithm and secret key that were used for encryption. The decryption process ensures the integrity and confidentiality of the data, making webhooks a secure method for automatic data updates. See examples below for implementing a secret key for decrpyting notifications sent from NomuPay.
Comments
0 comments
Please sign in to leave a comment.