Webhooks
Use incoming webhooks to get real-time updates
Listen for events on your YaYa Wallet account so your integration can automatically trigger reactions.
Why to use webhooks?
When building YaYa Wallet integrations, you might want your applications to receive transaction information as they
occur in your account, so that your backend systems can execute actions accordingly.
To enable webhook, you need to register webhook endpoint. After you register your endpoint, YaYa Wallet can push
real-time transaction event data to your application’s webhook endpoint when it happen in your YaYa Wallet account. YaYa
Wallet uses HTTPS to send webhook events to your app as a JSON payload.
Receiving webhook events are particularly useful for listening to asynchronous events, such as when a customer’s
confirms a payment request, a customer makes payment to your account, a recurring payment succeeds, or when collecting
subscription payments.
Structure of a webhook payload
The following example payload shows a webhook update information at the end of a transaction.
{
"id": "1dd2854e-3a79-4548-ae36-97e4a18ebf81",
"amount": 100,
"currency": "ETB",
"created_at_time": 1673381836,
"timestamp": 1701272333,
"cause": "Testing",
"full_name": "Abebe Kebede",
"account_name": "abebekebede1",
"invoice_url": "https://yayawallet.com/en/invoice/xxxx"
}
How to set up your webhook integration
To start receiving webhook events in your app, create and register a webhook endpoint by following the steps below.
1. Develop a webhook endpoint function to receive transaction data POST requests.
2. Test your webhook endpoint function locally
3. Register your endpoint within YaYa Wallet from the Webhooks section in your web dashboard
4. Secure your webhook endpoint
Create a webhook endpoint function
Set up an endpoint function that can accept webhook requests with a POST method. Your webhook endpoint function must use
HTTPS.
Set up your endpoint function so that it:
- Handles POST requests with a JSON payload.
- Quickly returns a successful status code (2xx) prior to any complex logic that could cause a timeout. For example,
you must return a 200 response before updating a customer’s invoice as paid in your accounting system.
Register and manage your webhook in YaYa Wallet
After testing your webhook endpoint, register the webhook endpoint’s accessible URL using the Webhooks section in the
API and Security so YaYa Wallet knows where to deliver events. The registered webhook endpoint must be publicly
accessible HTTPS URLs.
Secure your webhooks
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 YaYa Wallet. You can specify any string value as your secret hash, but we
recommend something random. You will use this secret to verify the request sent from YaYa Wallet.
After confirming that your webhook endpoint connection works as expected, secure the connection by using webhook
signature to verify that YaYa Wallet generated a webhook request and that it didn’t come from a server acting like YaYa
Wallet.
We will include the signature in our request to your webhook URL, in a header called YAYA-SIGNATURE. The value of
YAYA-SIGNATURE header is a HMAC SHA256 signature of the signed_payload using your secret key. The signed_payload is
formed by the concatenation of all the values of the payload encoded in UTF-8 format.
Verifying YAYA-SIGNATURE header should be done before processing the event.
Example to generate the signature in PHP
$secret_key = "test_key"; // you may keep this in env variable
$data = [
"id"=>"",
"amount"=> 100,
....
];
$data_for_seal = implode('', $data);
$signed_payload = utf8_encode($data_for_seal);
// YAYA-SIGNATURE
$signature = hash_hmac('sha256', $signed_payload, $secret_key);
Roll endpoint signing secrets periodically
The secret used for verifying that events come from YaYa Wallet is modifiable in the Webhooks section of the Dashboard.
To keep them safe, we recommend that you change secrets periodically, or when you suspect a compromised secret.
Verify events are sent from YaYa Wallet
YaYa Wallet sends webhook events from a set list of IP addresses. Only trust events coming from these IP addresses.
Additionally, verify webhook signatures to confirm that received events are sent from YaYa Wallet. YaYa Wallet signs
webhook events it sends to your endpoints by including a signature in each event’s YAYA-SIGNATURE header. This allows
you to verify that the events were sent by YaYa Wallet, not by a third party. Always ensure you verify signatures before
processing an event.
For verifying signatures, you must complete the following steps:
1. Extract the YAYA-SIGNATURE signature from the header
2. Prepare the signed_payload. The signed_payload string is created by concatenating all the values from the actual
JSON payload (that is, the request body) in the order they appear in the payload. For the payload example above, the
signed_payload would be the following
1dd2854e-3a79-4548-ae36-97e4a18ebf81100ETB16733818361701272333TestingAbebe Kebedeabebekebede1https://yayawallet.com/en/invoice/xxxx
3. Determine the expected signature. Compute an HMAC with the SHA256 hash function. Use the endpoint’s signing secret
as the key, and use the signed_payload string as the message.
4. Compare the signatures. Compare the signature in the header to the expected signature. For an equality match,
compute the difference between the current timestamp and the received timestamp, then decide if the difference is
within your tolerance.
Preventing replay attacks
A replay attack is when an attacker intercepts a valid payload and its signature, then re-transmits them. To mitigate
such attacks, YaYa Wallet includes a timestamp in the YAYA-SIGNATURE header. Because this timestamp is part of the
signed payload, it’s also verified by the signature, so an attacker can’t change the timestamp without invalidating the
signature. If the signature is valid but the timestamp is too old, you can have your application reject the payload.
We recommend a tolerance of 5 minutes between the timestamp and the current time. You can change this tolerance by
providing an additional parameter when verifying signatures. Use Network Time Protocol (NTP) to make sure that your
server’s clock is accurate and synchronises with the time on YaYa’s servers.
YaYa Wallet generates the timestamp and signature each time we send an event to your endpoint. If YaYa Wallet retries an
event (for example, your endpoint previously replied with a non-2xx status code), then we generate a new signature and
timestamp for the new delivery attempt.
Quickly return a 2xx response
Your endpoint must quickly return a successful status code (2xx) prior to any complex logic that could cause a timeout.
For example, you must return a 200 response before updating a customer’s invoice as paid in your accounting system.