Webhooks
This document goes through event listeners that can be called when certain actions are performed.
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.
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.
Example Code
app.post("/my/webhook/url", function(req, res) {
// Retrieve the request's body
var event = req.body;
// Do something with event
res.send(200);
});Structure of a webhook payload
The payload for your webhook will depend on if it was initiated by a transfer or by a transaction. You can check the difference by the type attribute. Transfer has "type": "Payout" while the transaction webhook will have the type of transaction, such as Payment Link , API, Event, Donation etc.
{
"event": "payout.success",
"type": "Payout",
"account_name": "Customer Name",
"account_number": "25190000000",
"bank_id": 855,
"bank_name": "telebirr",
"amount": "2000.00",
"charge": "60.00",
"currency": "ETB",
"status": "success",
"reference": "MYMER3434989",
"chapa_reference": "2o10dfs332U",
"bank_reference": "GT3412w3",
"created_at": "2023-08-27T19:23:22.000000Z",
"updated_at": "2023-08-27T19:23:23.000000Z"
} Webhook Event Types
Transaction Events
{
"event": "charge.success",
"first_name": "",
"last_name": "",
"email": null,
"mobile": "25190000000",
"currency": "ETB",
"amount": "400.00",
"charge": "12.00",
"status": "success",
"mode": "live",
"reference": "AP634JFwEbxd",
"created_at": "2023-08-27T19:21:18.000000Z",
"updated_at": "2023-08-27T19:21:27.000000Z",
"type": "API",
"tx_ref": "4FGFF4FFGD3",
"payment_method": "telebirr",
"customization": {
"title": null,
"description": null,
"logo": null
},
"meta": null
} Transfer Events
{
"event": "payout.success",
"type": "Payout",
"account_name": "Customer Name",
"account_number": "25190000000",
"bank_id": 855,
"bank_name": "telebirr",
"amount": "2000.00",
"charge": "60.00",
"currency": "ETB",
"status": "success",
"reference": "MYMER3434989",
"chapa_reference": "2o10dfs332U",
"bank_reference": "GT3412w3",
"created_at": "2023-08-27T19:23:22.000000Z",
"updated_at": "2023-08-27T19:23:23.000000Z"
} 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.
Example Code
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.