# Webhooks

Webhooks allow you to receive real-time updates about top-up statuses and other related events. When an event occurs, we automatically send data to the webhook URL you provide.

During onboarding, please provide the webhook URL you want to use for receiving delivery reports.

# Authorization

To ensure webhook requests are secure and originate from us, each request includes an X-Signature header.

You can verify this signature using your Webhook Secret and the raw request payload.

import crypto from "crypto"

export function verifyWebhookSignature(receivedSignature, secret, payload) {
    const expectedSignature = crypto
        .createHmac("sha256", secret)
        .update(payload)
        .digest("hex")

    const receivedBuffer = Buffer.from(receivedSignature)
    const expectedBuffer = Buffer.from(expectedSignature)

    // Ensure both Buffers have the same length
    if (receivedBuffer.length !== expectedBuffer.length) {
        return false
    }

    // Perform constant-time comparison
    return crypto.timingSafeEqual(receivedBuffer, expectedBuffer)
}

<?php

function verifyWebhookSignature($receivedSignature, $secret, $payload) {
    // Generate the expected signature using HMAC-SHA256
    $expectedSignature = hash_hmac("sha256", $payload, $secret);

    // Use hash_equals for constant-time comparison
    return hash_equals($expectedSignature, $receivedSignature);
}

# Request

# Success

A successful webhook request contains the following body:

Parameter	Type	Description
success	boolean	`true`
amount	integer	The amount of credit topped up.
phoneNumber	string	The recipient's phone number in an accepted format.
passthrough	string	The stringified value of the passthrough object sent in the recharge request.
operatorTransactionId	string	The transaction ID assigned by the operator.
operator	string	The identified mobile network operator.
rechargeId	string	Internal API ID used for debugging and support.

# Error

On error, the webhook contains the following body:

Parameter	Type	Description
success	boolean	`false`
error	string	The reason the top-up failed.
passthrough	string	The stringified value of the passthrough object sent in the recharge request.