Skip to main content
Webhooks enable your application to receive real-time notifications from VTULab. Instead of polling our API to check if a transaction is complete, we’ll push the status update directly to your server as soon as it happens.

Webhook URL

Configure your endpoint URL in the API Settings section of your dashboard.

​
Supported Events

Currently, we support the following event:
EventDescription
transaction.updatedFired when a transaction’s status changes (e.g., from processing to success or failed).

​
Payload Structure

When an event occurs, VTULab sends a POST request with a JSON body. 
{
  "event": "transaction.updated",
  "data": {
    "reference": "DATA_65E8F0B2...",
    "status": "success",
    "amount": 150,
    "type": "data",
    "network": "MTN",
    "phone_number": "08123456789",
    "created_at": "2024-03-06T12:00:00Z"
  }
}

​
Field Definitions

​
event
string
The type of event being sent.
​
data
object

​
Best Practices

​
1. Verification

Always verify that the webhook is originating from VTULab. We recommend checking the request’s source IP against our official list or verifying the signature if provided.

​
2. Acknowledge Promptly

Your server should return a 200 OK response within 5 seconds. If your processing logic takes longer, we recommend queuing the job and returning the response immediately.

​
3. Handle Idempotency

Ensure your webhook handler is idempotent. You might receive the same notification more than once in rare network scenarios. Use the reference field to track processed events.

​
Example Handler (Node.js)

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

app.use(express.json());

app.post('/webhooks/vtulab', (req, res) => {
  const { event, data } = req.body;

  if (event === 'transaction.updated') {
    console.log(`Transaction ${data.reference} updated to ${data.status}`);
    
    // Perform your business logic here (e.g., credit user, send email)
    
  }

  // Always return a 200 OK
  res.status(200).send('Webhook Received');
});

app.listen(3000, () => console.log('Webhook server running on port 3000'));