Webhooks

Webhooks allow you to receive real-time HTTP notifications when events happen on your account. RukkyHub sends POST requests to your configured endpoint URL with a JSON payload. Create and manage webhooks in Developer Portal → Webhooks.

Supported Events

Webhook Headers

X-Webhook-Event: vtu.success
X-Webhook-Signature: <hmac_sha256(payload_json, webhook_secret)>

Example Payload (VTU success)

{
  "event": "vtu.success",
  "occurred_at": "2026-04-05T12:00:00Z",
  "vtu": {
    "id": 1,
    "trx": "TRX_STRING",
    "category": "data",
    "service_name": "mtn-data",
    "phone": "08012345678",
    "amount": 123.45,
    "base_amount": 120.00,
    "profit_amount": 3.45,
    "provider": "third_party",
    "provider_ref": "ABC123",
    "status": "success",
    "meta": {},
    "created_at": "2026-04-05T12:00:00Z",
    "updated_at": "2026-04-05T12:00:05Z"
  }
}

Verifying Webhook Signatures

Always verify the X-Webhook-Signature header before trusting the payload. The signature is HMAC-SHA256 of the raw JSON payload using your webhook secret.

PHP verification:

<?php
$secret = getenv("SMM_WEBHOOK_SECRET");
$payload = file_get_contents("php://input");
$signature = $_SERVER["HTTP_X_WEBHOOK_SIGNATURE"] ?? "";

$expected = hash_hmac("sha256", $payload, $secret);
if (!hash_equals($expected, $signature)) {
  http_response_code(401);
  exit("Invalid signature");
}

http_response_code(200);
echo "OK";
// Process the event asynchronously (queue/job)

Node.js (Express) verification:

import crypto from "crypto";
import express from "express";

const app = express();
app.post("/webhook", express.raw({ type: "*/*" }), (req, res) => {
  const secret = process.env.SMM_WEBHOOK_SECRET;
  const payload = req.body.toString("utf8");
  const signature = req.header("X-Webhook-Signature") || "";

  const expected = crypto.createHmac("sha256", secret).update(payload).digest("hex");
  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
    return res.status(401).send("Invalid signature");
  }
  return res.status(200).send("OK");
});

Retry Policy

If your endpoint does not return a 2xx status within 5 seconds, the webhook will be retried up to 3 times with increasing delays (10s, 60s, 300s).

Testing Webhooks

You can send a test event from your Developer Portal → Webhooks section. Click the Test button next to any webhook to send a sample payload to your endpoint. This helps verify your endpoint is reachable and your signature verification logic works before receiving real events.

Webhook Delivery Logs

Your Developer Portal shows recent webhook delivery attempts including timestamp, event name, HTTP status code, and success/failure status. Use this to debug delivery issues.