Webhooks
Learn how to listen to events whenever certain actions occur on your integration.
Whenever certain transaction actions occur on your Vesicash integration, we trigger events which your application can listen to. This is where webhooks come in. A webhook is a URL on your server where we send payloads for such events. For example, if you implement webhooks, once a payment for a transaction is successful, we will immediately notify your server with a
payment.success event. Here is a list of events we can send to your webhook URL.We recommend that you use webhook to provide value to your customers over using a callback. Callbacks can fail if the network connection on a customer's device fails or is weak or if the device goes off after a transaction and several other situations that are outside both our and your control.
You can specify your webhook URL on your live dashboard if you've gone live or on your sandbox dashboard if you're still testing where we would send
POST requests to whenever an event occurs.Here are some things to note when setting up a webhook URL:
- 1.If using
.htaccess, remember to add the trailing/to the url you set. - 2.Do a test post to your URL and ensure the script gets the post body.
- 3.Ensure your webhook URL is publicly available (localhost URLs cannot receive events)
All you have to do to receive the event is to create an unauthenticated
POST route on your application. The event object is sent as JSON in the request body.NodeJS
PHP
// Using Express
app.post("/my/webhook/url", function(req, res) {
// Retrieve the request's body
var event = req.body;
// Do something with event
res.send(200);
});
<?php
// Retrieve the request's body and parse it as JSON
$input = @file_get_contents("php://input");
$event = json_decode($input);
// Do something with $event
http_response_code(200); // PHP 5.4 or greater
?>
It is important to verify that events originate from Vesicash to avoid delivering value based on a counterfeit event.
You can do any or both of the below to verify events from Paystack:
- 1.Validate the Signature - Valid events are raised with a header
X-Vesicash-Webhook-Secretwhich is essentially aHMAC SHA256signature of the event payload signed using your secret key. - 2.Watch the IPs - We only call your webhooks from these IPs:
52.204.32.79,3.85.176.242
You can whitelist these IPs. Any webhook from outside of these can safely be considered counterfeit.
NodeJS
PHP
var crypto = require('crypto');
var business_id = '<BUSINESS ID>';
var secret = process.env.SECRET_KEY . ':' . business_id;
// Using Express
app.post("/my/webhook/url", function(req, res) {
//validate event
var hash = crypto.createHmac('sha256', secret).update(JSON.stringify(req.body)).digest('hex');
if (hash == req.headers['x-vesicash-webhook-secret']) {
// Retrieve the request's body
var event = req.body;
// Do something with event
}
res.send(200);
});
<?php
function logWebhook($log) {
file_put_contents("post.log", $log, FILE_APPEND);
}
$body = json_decode(file_get_contents("php://input"), true);
// retrieve the signature sent in the request header's.
$signature = (isset($_SERVER['HTTP_X_VESICASH_WEBHOOK_SECRET']) ? $_SERVER['HTTP_X_VESICASH_WEBHOOK_SECRET'] : false);
/* It is a good idea to log all events received. Add code *
* here to log the signature and body to db or file */
if (!$signature) {
// only a post with rave signature header gets our attention
logWebhook("Signature Header is missing");
exit();
}
$private_key = '<YOUR PRIVATE KEY>';
$business_id = '<YOUR BUSINESS ID>';
$headerSignature = "$private_key:$business_id";
// Store the same signature on your server as an env variable and check against what was sent in the headers
$local_signature = hash_hmac('sha256', $headerSignature, $private_key);
// confirm the event's signature
if( $signature !== $local_signature ) {
// silently forget this ever happened
logWebhook("Signature Header Does Not Match");
exit();
}
logWebhook("Authenticated");
// PHP 5.4 or greater
// parse event (which is json string) as object
// Give value to your customer but don't give any output
// Remember that this is a call from vesicash's servers and
// Your customer is not seeing the response here at all
$response = json_decode($body);
http_response_code(200);
You should respond to an event with a
200 OK. We consider this an acknowledgement by your application. If your application responds with any status outside of the 2xx range, we will consider it unacknowledged and thus, continue to send it every hour for 72 hours. You don't need to send a request body or some other parameter as it would be discarded - we only pay attention to the status code.If your application is likely to start a long running task in response to the event, Vesicash may timeout waiting for the response and would ultimately consider the event unacknowledged and queue to be raised later. You can mitigate duplicity by having your application respond immediately with a 200 before it goes on to perform the rest of the task.
Payment Successful
Payment Failed
Disbursement Successful
Disbursement Failed
{
"event":"payment.success",
"data":{
"transaction_title":"Test Transaction Milestone One",
"transaction_id":"r1nwNapV09Stk4fhdUB7",
"payment_status":"success"
}
}
{
"event":"payment.failed",
"data":{
"transaction_title":"Test Transaction Milestone One",
"transaction_id":"r1nwNapV09Stk4fhdUB7",
"payment_status":"failed"
}
}
{
"event":"disbursement.success",
"data":{
"disbursement_id":3436452439,
"reference":"vc6430461564",
"status":"success"
}
}
{
"event":"disbursement.failed",
"data":{
"disbursement_id":3436452439,
"reference":"vc6430461564",
"status":"failed"
}
}
Here are the events we currently raise. We would add more to this list as we hook into more actions in the future.
Event | Description |
payment.success | A transaction was paid for successfully |
payment.failed | The payment for a transaction failed. |
disbursement.success | Funds disbursement was sent successfully |
disbursement.failed | Funds disbursement failed or was unsuccessful. |
Last modified 2yr ago