OnePay Webhook is a secure mechanism that combines various elements to create a notification and reaction system within an integration. It enables real-time communication and triggers specific actions based on events or updates.
Figuratively, webhook is like an email address that OnePay mails to notify you of an activity or event in your OnePay merchant account. The event could be the addition of a new customer into the Vault or any activity related to merchant payments. The webhook endpoint is the person receiving that mail who takes actions based upon the specific information received with respect to the activity or event.
From technical perspective, the webhook endpoint is just more code on your server, good code, which could be written in C#, Java, Node.js, or any programming language. The webhook endpoint has an associated URL (e.g., https://wexample.com/abcwebhooks). The OnePay notifications are activity or event based objects. The activity object contains all the relevant information about what just happened, including the type of activity and the data associated with that activity. The webhook endpoint uses the activity details to take any required actions, such as indicating that an order should be fulfilled or a receipt is confirmed.
Why Use OnePay Webhooks?
With OnePay Webhooks, Stay Updated on Object Status Changes.
Possible Actions for Your Webhook Endpoint:
- Notifying a ready to ship order
- Adjusting invoice records
- Logging customer entry
- Updating subscription packages
Utilizing OnePay webhooks allows you to leverage transactional data for various purposes such as logging, reporting, monitoring, and synchronization, enhancing the functionality and efficiency of your services or systems.
How to Use OnePay Webhooks?
OnePay sends data (transaction response) with hashed key in the header. This hashed key is a base64 encoded HMAC SHA-256 hash created from onepay_message and HMAC Secret key.
This payload data is sent to the configured webhook endpoint URL in Virtual Terminal.
How to configure webhook link?
From Virtual Terminal, under Manage Menu:
- The Webhook endpoint URL can be saved here.
- HMAC secret key can be generated on this page.
The details of transaction response object sent to the webhook endpoint is here: Payment Transactions
How to validate a request?
OnePay sends payload data to external services that will be authenticated with a hash-based message authentication code (HMAC).
The key used to create the HMAC is a shared secret, and you verify it by running the algorithm yourself with the payload and the key to re-create the HMAC.
This verifies that the sender of the message knows the secret key.
Create a hash using your consumer secret and a message obtained from incoming payload body.
- The consumer secret is your HMAC key
- The message is a concatenated string of Transaction Date Time, Transaction ID and Transaction Amount
Example:
Response message snip:
"transaction_datetime": "20200514T110623Z", "transaction_id": "1032708", "amount": "10.50",
- hash = message + secret
- message = transaction_datetime+transaction_id+amount --> concatenated string
If there is no transaction id, the message will have concatenated value with empty string
Example 1 : 20200514T110623Z103270810.50
Example 2 : 20200514T110623Z10.50