# 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 value of credit added to the recipient's account (in EUR).
`eurronApplied`	float	The EUR/RON exchange rate used to calculate the total cost.
`vatRate`	float	The VAT percentage applied to the order total.
`fastRecharge`	boolean	Indicates if the "Fast Recharge" priority feature was enabled.
`fastRechargeFee`	float	The additional fee charged for using the Fast Recharge feature.
`phoneNumber`	string	The recipient's phone number in an accepted format.
`passthrough`	string	Custom metadata string returned exactly as provided in the request.
`operatorTransactionId`	string	The unique reference ID assigned by the mobile network operator.
`operator`	string	The name of the identified mobile network operator.
`rechargeId`	string	Unique internal API identifier used for debugging and support.
`webhookName`	string	The identifier of the webhook triggered (if specified in the `/v1/recharge` request).

# 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.