Webhooks

Webhooks provide a way to receive notifications for your transactions in real-time. While your transaction is being processed, its status progresses until it is completed. This makes it very important to get the final status for that transaction, and that's where webhooks are very beneficial.

Put simply, a webhook URL is an endpoint on your server that can receive API requests from Blinqpay checkout server. Note that the request is going to be an HTTP POST request.

Setting your Webhook URL

You can specify your webhook URL in the API Keys and Webhook tab of the Settings page of your dashboard. Make sure that the webhook URL is unauthenticated and publicly available.

The request to the webhook URL comes with a payload, and this payload contains the details of the transaction for which you are being notified.

Verifying Webhooks Request

It is important to verify that requests are coming from Blinqpay to avoid delivering value based on a counterfeit request. To verify our requests, you need to validate the signature assigned to the request. The request will have a header called Signature that will contain a signature the receiving app can use to verify the payload hasn't been tampered with.

Valid requests are sent with a header signature which is essentially an HMAC SHA256 signature of the request payload signed using your secret key.

const crypto = require(“crypto”);
const secretKey = BLQLIVESECK-******

router.post(‘/your_webhook_url’, (req, res, next) => {
  const hash = crypto.createHmac('sha256', secretKey).update(JSON.stringify(req.body.data)).digest('hex');

   If (hash === req.headers[‘signature’]) {
     // Continue with the request functionality
   } else {
     // Don’t do anything, the request is not from us.
   }
});

function verifySignature($secretKey, $paymentData) {
  
  $computedSignature = hash_hmac('sha256', json_decode($paymentData), $secretKey);
  
  if ($computedSignature === $_SERVER['signature']) {
     // Continue with the request functionality
   } else {
     // Don’t do anything, the request is not from us.
   }
}

Responding to Webhooks Request

It is important to respond to the requests with a 200 status code to acknowledge that you have received the requests. Blinqpay Checkout does not pay attention to any request parameters apart from the request status code.

Please note that if any other response code is received, or there’s a timeout while sending the request, we retry the request periodically 5 times after which retries stop.

Best Practices

It is recommended to do the following when receiving webhook notifications from us:

• Keep track of all notifications received: It’s important to keep track of all notifications you’ve received. When a new notification is received proceed to check that this has not been processed before giving value. A retry of already processed notifications can happen if we do not get a 200 HTTP Status code from your notification URL, or if there was a request time out.
• Acknowledge receipt of notifications with a 200 HTTP status code: It’s recommended you immediately acknowledge receipt of the notification by returning a 200 HTTP Status code before proceeding to perform other logics, failure to do so might result in a timeout which would trigger a retry of such notification.