Vtunaija API Webhook Integration Guide

Laravel

Example Laravel route:

use App\Http\Controllers\WebhookController;
use Illuminate\Support\Facades\Route;
 
Route::post(
    '/webhooks/Vtunaija',
    [WebhookController::class, 'handle']
);

Example controller:

<?php

namespace App\Http\Controllers;

use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;

class WebhookController extends Controller
{
    public function handle(Request $request): JsonResponse
    {
        $secret = config('services.Vtunaija.webhook_secret');

        if (!$secret) {
            return response()->json([
                'error' => 'Webhook secret is not configured'
            ], 500);
        }

        $rawBody = $request->getContent();

        $timestamp = (string)$request->header(
            'X-Webhook-Timestamp',
            ''
        );

        $signature = (string)$request->header(
            'X-Webhook-Signature',
            ''
        );

        $eventId = (string)$request->header(
            'X-Webhook-Event-ID',
            ''
        );

        if (
            $timestamp === '' ||
            $signature === '' ||
            $eventId === ''
        ) {
            return response()->json([
                'error' => 'Missing required webhook headers'
            ], 400);
        }

        $signatureContent = $timestamp . '.' . $rawBody;

        $expectedSignature = hash_hmac(
            'sha256',
            $signatureContent,
            $secret
        );

        if (!hash_equals($expectedSignature, $signature)) {
            return response()->json([
                'error' => 'Invalid webhook signature'
            ], 401);
        }

        $payload = json_decode($rawBody, true);

        if (!is_array($payload)) {
            return response()->json([
                'error' => 'Invalid JSON payload'
            ], 400);
        }

        $payloadEventId = (string)(
            $payload['event_id'] ?? $eventId
        );

        if ($payloadEventId === '') {
            return response()->json([
                'error' => 'Missing event_id'
            ], 400);
        }

        /*
         * Check your database here for an existing event_id.
         *
         * If already processed:
         *
         * return response()->json([
         *     'status' => 'success'
         * ]);
         */

        /*
         * Process the transaction here.
         *
         * After successful processing, store the event ID in a
         * table having a UNIQUE constraint on event_id.
         */

        return response()->json([
            'status' => 'success'
        ]);
    }
}

Node.js / Express

const express = require('express');
const crypto = require('crypto');

const app = express();

const webhookSecret = process.env.WEBHOOK_SECRET;

app.use(express.json({
    verify: (req, res, buffer) => {
        req.rawBody = buffer.toString('utf8');
    }
}));

function verifySignature(body, timestamp, receivedSignature) {
    if (!body || !timestamp || !receivedSignature) {
        return false;
    }

    if (!webhookSecret) {
        return false;
    }

    const signatureContent = timestamp + '.' + body;

    const expectedSignature = crypto
        .createHmac('sha256', webhookSecret)
        .update(signatureContent, 'utf8')
        .digest('hex');

    const expectedBuffer = Buffer.from(
        expectedSignature,
        'utf8'
    );

    const receivedBuffer = Buffer.from(
        receivedSignature,
        'utf8'
    );

    if (expectedBuffer.length !== receivedBuffer.length) {
        return false;
    }

    return crypto.timingSafeEqual(
        expectedBuffer,
        receivedBuffer
    );
}

app.post('/webhooks/Vtunaija', async (req, res) => {
    try {
        const rawBody = req.rawBody || '';

        const timestamp =
            req.get('X-Webhook-Timestamp') || '';

        const signature =
            req.get('X-Webhook-Signature') || '';

        const eventId =
            req.get('X-Webhook-Event-ID') || '';

        if (!eventId) {
            return res.status(400).json({
                error: 'Missing webhook event ID'
            });
        }

        if (!verifySignature(
            rawBody,
            timestamp,
            signature
        )) {
            return res.status(401).json({
                error: 'Invalid webhook signature'
            });
        }

        const payload = req.body;

        if (
            !payload ||
            typeof payload !== 'object'
        ) {
            return res.status(400).json({
                error: 'Invalid JSON payload'
            });
        }

        /*
         * Check eventId in your database before processing.
         *
         * If the event has already been processed, return 200.
         */

        /*
         * Process the transaction here.
         *
         * After successful processing, save the event ID.
         */

        return res.status(200).json({
            status: 'success'
        });

    } catch (error) {
        console.error(
            'Webhook processing error:',
            error
        );

        return res.status(500).json({
            error: 'Processing failed'
        });
    }
});

const port = process.env.PORT || 3000;

app.listen(port, () => {
    console.log(
        `Webhook server listening on port ${port}`
    );
});

Python / Flask

import os
import hmac
import hashlib

from flask import Flask, request, jsonify

app = Flask(__name__)

WEBHOOK_SECRET = os.environ.get(
    "WEBHOOK_SECRET",
    ""
)


def verify_signature(
    raw_body: bytes,
    timestamp: str,
    received_signature: str
) -> bool:

    if not timestamp or not received_signature:
        return False

    if not WEBHOOK_SECRET:
        return False

    signature_content = (
        timestamp.encode("utf-8")
        + b"."
        + raw_body
    )

    expected_signature = hmac.new(
        WEBHOOK_SECRET.encode("utf-8"),
        signature_content,
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(
        expected_signature,
        received_signature
    )


@app.route(
    "/webhooks/Vtunaija",
    methods=["POST"]
)
def handle_webhook():

    try:
        raw_body = request.get_data()

        timestamp = request.headers.get(
            "X-Webhook-Timestamp",
            ""
        )

        signature = request.headers.get(
            "X-Webhook-Signature",
            ""
        )

        event_id = request.headers.get(
            "X-Webhook-Event-ID",
            ""
        )

        if not event_id:
            return jsonify({
                "error": "Missing webhook event ID"
            }), 400

        if not verify_signature(
            raw_body,
            timestamp,
            signature
        ):
            return jsonify({
                "error": "Invalid webhook signature"
            }), 401

        payload = request.get_json(
            silent=True
        )

        if not isinstance(payload, dict):
            return jsonify({
                "error": "Invalid JSON payload"
            }), 400

        /*
         * Check event_id in your database before processing.
         *
         * If already processed, return HTTP 200.
         *
         * Process the transaction here.
         *
         * After successful processing, store event_id.
         */

        return jsonify({
            "status": "success"
        }), 200

    except Exception as error:

        app.logger.exception(
            "Webhook processing error"
        )

        return jsonify({
            "error": "Processing failed"
        }), 500


if __name__ == "__main__":
    app.run(
        host="0.0.0.0",
        port=int(
            os.environ.get("PORT", "3000")
        ),
        debug=False
    )

cURL

The following example demonstrates how a signed JSON webhook request can be generated and sent from a Unix-like environment.

WEBHOOK_URL="https://example.com/webhooks/Vtunaija"
SECRET="YOUR_WEBHOOK_SECRET"
TIMESTAMP=$(date +%s)

PAYLOAD='{
  "event_id": "ev_test_123",
  "event_type": "transaction.success",
  "transaction_id": "req_test_abc",
  "transaction_internal_id": 999999,
  "service": "DATA",
  "provider": "test",
  "provider_reference": "TEST-123",
  "status": "successful",
  "amount": "1000.00",
  "plan_amount": "1000.00",
  "mobile_number": "08012345678",
  "network": "MTN",
  "data_type": "SME",
  "api_response": "Test webhook",
  "balance_before": "5000.00",
  "balance_after": "4000.00",
  "created_at": "2026-08-27T19:00:00Z",
  "profit": "100.00",
  "user_type": "Basic"
}'

SIGNATURE_CONTENT="${TIMESTAMP}.${PAYLOAD}"

SIGNATURE=$(printf '%s' "$SIGNATURE_CONTENT" \
    | openssl dgst -sha256 \
    -hmac "$SECRET" \
    -hex \
    | awk '{print $2}')

curl -X POST "$WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Timestamp: $TIMESTAMP" \
  -H "X-Webhook-Event-ID: ev_test_123" \
  -H "X-Webhook-Signature: $SIGNATURE" \
  --data "$PAYLOAD"