How to Set Up RukkyHub API Webhooks for Order and Transaction Updates

How to Set Up RukkyHub API Webhooks for Order and Transaction Updates

RukkyHub API webhooks allow your application to receive HTTP notifications when selected events occur on your account. Instead of repeatedly requesting transaction or order status updates, your application can receive a notification when a supported event happens.

Webhooks are useful for reseller platforms, business dashboards, automated order management, and applications that need to keep transaction records updated.

What Are RukkyHub API Webhooks?

A webhook is an HTTP notification sent by RukkyHub to an endpoint on your application. RukkyHub sends a POST request containing a JSON payload describing the event.

Your application receives the request, verifies its authenticity, and processes the event. For example, a webhook can notify your application when an SMM order changes status or a VTU transaction succeeds or fails.

Supported Webhook Events

RukkyHub documents the following webhook events:

• order.created — a new SMM order has been created.
• order.status_changed — an SMM order's status has changed.
• order.refunded — an SMM order has been refunded.
• vtu.status_changed — a VTU transaction's status has changed.
• vtu.processing — a VTU transaction is processing.
• vtu.success — a VTU transaction completed successfully.
• vtu.failed — a VTU transaction failed.
• deposit.success — a deposit was credited to the account.
• withdraw.approved — a withdrawal request was approved.

Select the events relevant to your integration and handle each event according to its meaning. A status-change notification is not necessarily a final success notification.

Step 1: Prepare Your Webhook Endpoint

Before configuring a webhook, create an endpoint in your application that can receive HTTP POST requests containing JSON data.

Your endpoint should:

• Be accessible to RukkyHub over HTTPS.
• Accept POST requests and read the raw request body.
• Verify the webhook signature before trusting the payload.
• Return a successful HTTP status quickly after accepting a valid event.
• Process heavier tasks asynchronously using a queue or background job.

For example, your application might use an endpoint such as https://yourdomain.com/webhooks/rukkyhub. Replace this example with an actual endpoint on your own server.

Step 2: Create a Webhook in the Developer Portal

1. Sign in to your RukkyHub account.
2. Open the Developer Portal.
3. Navigate to the Webhooks section.
4. Create and configure a webhook using your application's endpoint URL.
5. Select the events your application needs to receive.
6. Save the configuration and securely store any webhook secret provided by the platform.

The available configuration fields and options are displayed in the Developer Portal. Follow the instructions shown there for the webhook you create.

Step 3: Understand Webhook Headers and Payloads

RukkyHub webhook requests include an event header and a signature header:

• X-Webhook-Event identifies the event type.
• X-Webhook-Signature contains an HMAC-SHA256 signature calculated from the raw JSON payload and your webhook secret.

A VTU success notification has a payload structure similar to the following example:

{  "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,    "status": "success"  } }

This is an illustrative payload based on the documented structure. Actual values depend on the event and transaction. Use the transaction reference and other available fields to match the notification to the correct record in your application.

Step 4: Verify the Webhook Signature

Signature verification is essential. Do not trust a request simply because it claims to come from RukkyHub or contains a familiar transaction reference.

RukkyHub documents the signature as an HMAC-SHA256 digest of the raw JSON request body using your webhook secret. Your application should calculate the expected signature and compare it with the received signature before processing the event.

The following PHP example follows the official verification approach:

<?php $secret = getenv("RUKKYHUB_WEBHOOK_SECRET"); $payload = file_get_contents("php://input"); $signature = $_SERVER["HTTP_X_WEBHOOK_SIGNATURE"] ?? ""; if (!$secret || !$signature) {    http_response_code(401);    exit("Missing webhook authentication"); } $expected = hash_hmac("sha256", $payload, $secret); if (!hash_equals($expected, $signature)) {    http_response_code(401);    exit("Invalid signature"); } // Signature verified. // Decode and validate the payload before processing it. $data = json_decode($payload, true); if (!is_array($data)) {    http_response_code(400);    exit("Invalid JSON payload"); } // Queue the event for processing. // Return promptly after accepting the event. http_response_code(200); echo "OK";

Store the webhook secret in a server-side environment variable or secrets manager. Do not place it in public JavaScript or expose it in client responses.

Always verify the signature against the exact raw request body before decoding or modifying the JSON. If you use another programming language, follow the equivalent signature-verification method in the official documentation.

Step 5: Process Events Safely

After signature verification succeeds, validate the event name and required payload fields before updating your database.

• Match the event to the correct order or transaction.
• Update the record using the verified event information.
• Check the current record state before applying an update.
• Avoid processing the same notification twice.
• Queue email notifications, reporting, and other time-consuming work outside the request handler.

Do not assume that notifications will always arrive in the order you expect. Your application should handle duplicate or delayed notifications without corrupting transaction records.

Step 6: Test Your Webhook

1. Open the Developer Portal and go to Webhooks.
2. Find the webhook you want to test.
3. Use the Test button next to the webhook to send a sample payload.
4. Confirm that your endpoint receives the request.
5. Check that signature verification works correctly.
6. Confirm that the endpoint returns a successful HTTP response and processes the event as expected.

Testing helps identify configuration, connectivity, and signature-verification problems before your integration receives real notifications.

Step 7: Understand Webhook Retries

According to the RukkyHub webhook documentation, if your endpoint does not return a 2xx HTTP status within five seconds, the webhook is retried up to three times with increasing delays of 10 seconds, 60 seconds, and 300 seconds.

To reduce avoidable retries:

• Keep the webhook handler lightweight.
• Verify the signature efficiently.
• Queue longer-running work instead of completing it before responding.
• Return a successful response after a valid event has been safely accepted.
• Investigate failed deliveries in the Developer Portal.

Do not return success for an invalid signature. Reject unauthenticated requests and investigate the reason for the failure.

Step 8: Review Webhook Delivery Logs

The RukkyHub Developer Portal provides recent webhook delivery attempts, including timestamps, event names, HTTP status codes, and delivery success or failure information.

If an event is not reaching your application, use these logs to check whether the request was attempted and how your endpoint responded.

Common Webhook Problems

My endpoint does not receive notifications.

Confirm that the endpoint URL is correct, publicly accessible over HTTPS, and configured in the Developer Portal. Check the delivery logs for failed attempts.

Signature verification fails.

Use the correct webhook secret and calculate the HMAC-SHA256 signature from the raw request body. Do not decode and re-encode the JSON before verifying the signature.

My webhook receives repeated notifications.

Make your event handler idempotent so that processing the same notification more than once does not create duplicate orders, payments, or account updates.

My endpoint is timing out.

Return a response promptly after verifying and safely accepting the event. Move longer operations to a background queue.

An event is received but the application does not update.

Check the event name, payload structure, transaction reference, application logs, and database update logic. Make sure your application handles the particular event type.

Webhook Security Checklist

• Use HTTPS for your webhook endpoint.
• Verify every webhook signature before trusting its payload.
• Store webhook secrets securely.
• Validate event names and payload fields.
• Prevent duplicate processing.
• Keep handlers fast and process lengthy tasks asynchronously.
• Review delivery logs when notifications fail.

Official RukkyHub Developer Resources

• Webhooks Documentation — supported events, signatures, retries, and delivery logs.
• API Reference — API actions and transaction status requests.
• Authentication Guide — API key scopes and security practices.
• API Error Codes — troubleshooting API request failures.

Frequently Asked Questions

Do webhooks replace API status checks?

Webhooks can reduce the need for repeated status checks by notifying your application when supported events occur. Your application may still need API requests for reconciliation or to retrieve additional information.

Should I trust a webhook without verifying its signature?

No. Verify the signature using the configured webhook secret before trusting the payload or making changes to transaction records.

What happens if my endpoint does not respond in time?

RukkyHub documents retry attempts when an endpoint does not return a 2xx response within five seconds. Keep your handler fast and review delivery logs if retries continue.

Can I test webhooks before going live?

Yes. Use the Test button in the Developer Portal's Webhooks section to send a sample event and verify your endpoint and signature-handling logic.