What are Webhooks
Whenever transactions take place, certain events will be triggered that cooperate with your application. Webhook is a URL on your server that sends these events.
When to use webhooks
Webhooks are supported for all kinds of payment methods, but they’re especially useful for methods and events that happen outside your application’s control, such as:
- a pending payment transaction to successful.
These are all asynchronous actions—they are not controlled by your application, so you won’t know when they are completed, unless we notify you or you check later.
Setting up a webhook allows us to notify you when these payments are completed. Within your webhook endpoint, you can then:
- Update your order records when the status of a pending payment id updated to successful.
Structure of a webhook payload
All webhook payloads follow the same basic structure.
- an
eventfield describing the type of event - a
dataobject. The contents of this object will vary depending on the event, but typically it will contain details of the event including:status,id, payment and customer details.
Enabling webhooks
Here’s how to setup a webhook on your Chapa account:
- Login to your dashboard and go to your profile settings.
- Navigate to Webhooks tab to add your webhook URL and secret hash
- That’s it!
Recieving an event
A webhook URL is an endpoint on your server where you can receive notifications about such events. When an event occurs, we’ll make a POST request to that endpoint, with a JSON body containing the details about the event, including the type of event and the data associated with it.
app.post("/my/webhook/url", function(req, res) {
// Retrieve the request's body
var event = req.body;
// Do something with event
res.send(200);
});
Verify webhook origin
When enabling webhooks, you should set a secret hash. Since webhook URLs are publicly accessible, the secret hash allows you to verify that incoming requests are from Chapa. You can specify any string value as your secret hash, but we recommend something random. You should also store it as an environment variable on your server.
We will include it in our request to your webhook URL, in a header called Chapa-Signature. The value of Chapa-Signature header is a HMAC SHA256 signature of your secret key signed using your secret key.
Also we will include another header x-chapa-signature.
In the webhook endpoint, check eitherChapa-Signature or x-chapa-signature headers present and that it matches the secret hash you set. If either one of headers is missing, or the value doesn’t match, you can discard the request, as it isn’t from Chapa.
The value of x-chapa-signature header is a HMAC SHA256 signature of the event payload signed using your secret key.
Verifying either x-chapa-signature or Chapa-Signature header should be done before processing the event.
var crypto = require('crypto');
var secret = process.env.SECRET_KEY;
// Using Express
app.post("/my/webhook/url", function(req, res) {
//validate event
const hash = crypto.createHmac('sha256', secret).update(JSON.stringify(req.body)).digest('hex');
if (hash == req.headers['Chapa-Signature']) {
// Retrieve the request's body
const event = req.body;
// Do something with event
}
res.send(200);
});
Acknowledging Webhook Event
When your webhook URL receives an event, it needs to parse and acknowledge the event. Acknowledging an event means returning a 200 OK in the HTTP header. Without a 200 OK in the response header, we’ll keep sending events for the next 72 hours every 10 minutes for the 5 tries.
