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.
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.
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 ,
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
In the webhook endpoint, check either
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.
Chapa-Signature header should be done before processing the event.
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.