Home Integration and API Webhooks

Webhooks

Last updated on Apr 16, 2024

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.