Webhooks - IA-Café API Documentation

🔔 What are Webhooks?

Webhooks allow your application to receive real-time notifications when events occur. Instead of constantly polling our API, we'll send HTTP POST requests to your URL.

⚡

Real-time Updates

Know instantly when a transaction completes

🎫

Automatic Token Delivery

Get electricity tokens immediately when ready

🔒

Secure

Signed payloads to verify authenticity

🔧 Setup Your Webhook

POST /devapi/v1/webhook/endpoint

cURL - Register Webhook

curl -X POST "https://iacafe.com.ng/devapi/v1/webhook/endpoint" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhook/iacafe"
  }'

                    Response
                

{
  "success": true,
  "message": "Webhook endpoint added",
  "secret": "whsec_a1b2c3d4e5f6g7h8i9j0..."
}
                

⚠️

Save Your Secret!

The secret is only shown once. Save it securely - you'll need it to verify webhook signatures.

📋 Webhook Events

Event	Description	When Fired
`transaction.created`	A new transaction was created	Immediately when order is placed
`transaction.status_changed`	Transaction status changed	When completed, failed, or refunded

📦 Payload Example (Electricity)

                    Webhook Payload
                    
                

{
  "id": "evt_elec_success_001",
  "type": "transaction.status_changed",
  "created_at": "2024-05-20T10:05:00.000Z",
  "data": {
    "order_id": 12345,
    "request_id": "elec_ikeja_1704067200_abc123",
    "status": "completed-api",
    "category": "electricity",
    "service_id": "ikeja-electric",
    
    // ⚡ THE ELECTRICITY TOKEN!
    "token": "1234-5678-9012-3456-7890",
    "units": "45.5 kWh",
    "band": "Band A",
    
    "customer_name": "John Doe",
    "customer_address": "123 Lagos Street",
    "amount": 5000,
    "amount_charged": 4975
  }
}
                

🔐 Signature Verification

🚨

Security Warning

Never process webhooks without verifying the signature. Anyone could send fake webhooks to your endpoint!

The signature is computed as:

                    Signature Formula
                
signature = HMAC-SHA256(webhook_secret, timestamp + "." + raw_body)

Node.js Example

Node.js Verification

const crypto = require('crypto');

const WEBHOOK_SECRET = 'whsec_your_secret_here';

app.post('/webhook/iacafe', (req, res) => {
  const signature = req.headers['x-vtu-signature'];
  const timestamp = req.headers['x-vtu-timestamp'];
  const payload = req.body.toString();

  const expectedSig = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(timestamp + '.' + payload)
    .digest('hex');

  if (signature !== expectedSig) {
    return res.status(401).send('Invalid signature');
  }

  // Process webhook...
  const event = JSON.parse(payload);
  console.log('Received:', event.type);

  res.status(200).json({ received: true });
});

✅ Best Practices

🔒 Always Verify Signatures

Never skip signature verification.

⚡ Respond Quickly

Return 200 within 5 seconds. Process heavy tasks asynchronously.

🔄 Handle Duplicates

Store processed webhook IDs to avoid processing twice.

🔐 Use HTTPS

Your webhook endpoint must use SSL/TLS.