> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rapidtopup.com.ng/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receive real-time HTTP POST notifications when transaction statuses change. The recommended alternative to polling.

## Overview

Configure a **Webhook URL** in your Developer Dashboard to receive signed HTTP `POST` notifications whenever a transaction status changes to `success` or `failed`.

> [!TIP]
>
> Webhooks are far more efficient than polling `/requery`. Set one up before going live.

***

## Webhook Payload

```json theme={null}
{
  "event": "transaction.updated",
  "data": {
    "reference": "RTU-DATA-20261003-AB12CD",
    "service": "mtn-data",
    "type": "data",
    "amount": 250.00,
    "status": "success",
    "phone_number": "08012345678",
    "token": null,
    "created_at": "2026-10-03T08:00:00Z",
    "updated_at": "2026-10-03T08:01:15Z"
  }
}
```

### Status Values

| Status | Meaning |
| - | - |
| `success` | Transaction delivered successfully |
| `failed` | Transaction failed. Wallet has been automatically refunded |

***

## Verifying Signatures

Every webhook is signed using **HMAC SHA-512**. You must verify this signature to ensure the request is genuinely from RapidTopup.

**Steps:**

1. Get your **Webhook Secret** from the Developer Dashboard
2. Read the **raw request body** as a string (before JSON parsing)
3. Compute `HMAC-SHA512(raw_body, webhook_secret)`
4. Compare to the `X-RapidTopup-Signature` header using constant-time comparison

```php PHP theme={null}
<?php

$webhookSecret = 'rtu_wh_sec_YOUR_WEBHOOK_SECRET';
$rawPayload    = file_get_contents('php://input');
$signature     = $_SERVER['HTTP_X_RAPIDTOPUP_SIGNATURE'] ?? '';

$computedHash  = hash_hmac('sha512', $rawPayload, $webhookSecret);

if (!hash_equals($computedHash, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

$event = json_decode($rawPayload, true);

if ($event['event'] === 'transaction.updated') {
    $reference = $event['data']['reference'];
    $status    = $event['data']['status'];
    // Update your database order status here
}

http_response_code(200);
echo 'OK';
```

```javascript Node.js theme={null}
const crypto = require('crypto');

app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const webhookSecret = process.env.RAPIDTOPUP_WEBHOOK_SECRET;
  const signature     = req.headers['x-rapidtopup-signature'];
  const rawBody       = req.body; // Must be raw Buffer

  const computedHash  = crypto
    .createHmac('sha512', webhookSecret)
    .update(rawBody)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(computedHash), Buffer.from(signature))) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(rawBody);

  if (event.event === 'transaction.updated') {
    const { reference, status } = event.data;
    // Update your database here
  }

  res.status(200).send('OK');
});
```

***

## Retry Policy

If your server returns a non-`2xx` response or times out after 10 seconds, we retry with exponential backoff:

| Attempt | Wait Before Retry |
| - | - |
| 1st retry | 1 minute |
| 2nd retry | 5 minutes |
| 3rd retry | 15 minutes |
| 4th retry | 1 hour |
| 5th (final) | No further retries |

> [!WARNING]
>
> Always return HTTP `200 OK` from your webhook endpoint immediately, even if you're processing the event asynchronously in a queue. Otherwise we'll treat it as a failure and keep retrying.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.