What is a Webhook?
Webhooks are a clever way for applications to exchange real-time information whenever specific events occur, all without the need for constant polling. They function as a passive bridge between two systems, communicating through HTTP POST requests. Once you've set up OnePay webhooks, you'll receive timely event notifications for every activity or function generated within the OnePay's flow.
Why Choose Webhooks?
Webhooks are highly recommended for keeping your system in sync with payment progress and status updates. Thanks to automatic event notifications, your system can avoid the overhead of frequent requests to OnePay. Instead, you'll be able to process payment information precisely when you need it.
What You Need to Know Before Getting Started
Before diving into OnePay's webhooks, there are a few prerequisites:
Create a Public REST API: You'll need to establish a public REST API capable of receiving event notifications via POST requests. Importantly, this REST API should require authentication or impose access restrictions through headers.
Secure Communication: Even though you're using a public API, rest assured that your communication with OnePay event notifications will remain secure. These notifications won't be accessible to the public and will only communicate with your REST API through a unique URL.
By following these steps, you can seamlessly integrate OnePay webhooks into your system for real-time updates without the hassle of constant requests.
Signing webhooks
During the setup process, it's customary to create, securely store, and exchange a confidential key between your application and the recipient application, which is intended to receive webhooks. OnePay utilizes this secret key to authenticate webhook calls.
By default, OnePay incorporates a "signature" header within the request, housing a unique signature. This signature enables the receiving application to verify the integrity of the payload, ensuring it remains unaltered during transit.
Here's the method through which this signature is computed:
secret = 'wh_tok_BzgFuoj36cyuN0QAMtcTFVgIlU7doHZCugHalwq1non79lVrP3qV'
hmac('sha256', json, secret)
HMAC
HMAC is a MAC/keyed hash, not a cipher. It's not designed to be decrypted. If you want to encrypt something, use a cipher, like AES, preferably in an authenticated mode like AES-GCM.
Even knowing the key, the only way to "decrypt" is guessing the whole input and then comparing the output.
Authentication Header for Webhooks
In every request, you will receive an authentication header containing an authorization token. It's important to note that this token is distinct from the secret key. This header can also be used to verify the origin of the information being transmitted.
x-webhook-token: 'wh_hdr_uqviEXJhuh59KfoQW9qwNMmH8A4vJZkCDDkskHBcknfvmTejImqr'
Setup tokens on the platform
You can set up the webhooks directly in the admin in the next url: Admin
Testing
For more extensive local environment development, we highly recommend utilizing urls ngrok.com.