Telesend Callbacks

This page lists the available callbacks and their payloads.

Callbacks are used to notify partners about important events related to our services.
Each callback can be uniquely identified by its eventType field.

---

Registering a Callback

To start receiving callbacks, you must register your callback endpoint in the partner portal API Management page. https://telesend.et/manage-apis Make sure your endpoint is publicly accessible.

Since callback URLs are public, you need a way to verify that the callback request actually originated from Telesend.

1. When you register your callback endpoint, you must also generate a secret hash (random string, length of your choice).
2. Telesend will use this secret hash to sign the body of each callback request using HMAC-SHA256.
3. We include the signature in the x-telesend-signature header.

Upon receiving a callback request, you can use the request body, the header, and your secret hash to verify authenticity.

---

Signature Verification (TypeScript Example)

import * as crypto from "crypto";

function verifySignature(req, secretHash: string): boolean {
  const payload = JSON.stringify(req.body) + "\n"; 
  const signature = req.headers["x-telesend-signature"] as string;

  const expected = crypto
    .createHmac("sha256", secretHash)
    .update(payload)
    .digest("hex");

  return signature === expected;
}

Types of Callbacks

1. Health Check Callbacks

Sometimes our Telebirr API may enter an unrecoverable state that requires manual intervention. During such times, we send a callback with the event type API_STATUS_CHANGE to notify you of downtime or recovery.

The callback payload includes the event type and a single field indicating whether the API is currently available:

{
    "eventType": "API_STATUS_CHANGE", 
    "isEnabled": true | false, 
}

• isEnabled = false → our API is going down for some time. You can use this to inform your users accordingly.
• isEnabled = true → the API is back up again.

2. Voucher Redeem Callbacks

After you generate a gift voucher, merchants redeem it through the Merchant Redemption APIs (portal or merchant API integration). When a redemption completes and your account is configured for voucher redeem notifications, Telesend may send a callback with event type VOUCHER_REDEEMED.

The callback payload will be

{
        eventType: 'VOUCHER_REDEEMED',
        voucherId: number, // voucherId
        message: string, // the response we got for the redeem attempt from etho telecom
        voucherCode: string, // voucher code for the redeemed voucher
        redeemedAmount: number, // redeemed amount
        status: 'PARTIALLY_REDEEMED' | 'REDEEMED' | 'EXPIRED', // current status of voucher
}

NOTE

Confirm with the OmniVAS / Telesend business team which redeem webhook events are enabled for your account after the merchant redemption platform migration.