Webhooks

{
  "id": "evt_1760425200100_a1b2c3d4",
  "event": "sms.sent",
  "delivery_id": "del_1760425200100_1f2e3d4c",
  "created_at": "2026-10-28T16:10:00.100Z",
  "data": {
    "message_id": "msg_1760425200000_a1b2c3d4",
    "to": "+256750625684",
    "recipient": "+256750625684",
    "sender_id": "UGATEXT",
    "status": "sent",
    "network": "MTN Uganda",
    "mode": "live",
    "units": 1,
    "cost_ugx": 25,
    "currency": "UGX",
    "sent_at": "2026-10-28T16:10:00.100Z"
  }
}

{
  "id": "evt_1760425202720_b2c3d4e5",
  "event": "sms.delivered",
  "delivery_id": "del_1760425202720_5a6b7c8d",
  "created_at": "2026-10-28T16:10:02.720Z",
  "data": {
    "message_id": "msg_1760425200000_a1b2c3d4",
    "to": "+256750625684",
    "recipient": "+256750625684",
    "sender_id": "UGATEXT",
    "status": "delivered",
    "network": "MTN Uganda",
    "mode": "live",
    "units": 1,
    "cost_ugx": 25,
    "currency": "UGX",
    "provider_reference": "pdr_1760425200120_a1b2c3d4",
    "delivered_at": "2026-10-28T16:10:02.720Z"
  }
}

{
  "id": "evt_1760425205400_c3d4e5f6",
  "event": "sms.failed",
  "delivery_id": "del_1760425205400_9e8f7a6b",
  "created_at": "2026-10-28T16:10:05.400Z",
  "data": {
    "message_id": "msg_1760425200000_a1b2c3d4",
    "to": "+256750625684",
    "recipient": "+256750625684",
    "sender_id": "UGATEXT",
    "status": "failed",
    "network": "Airtel Uganda",
    "mode": "live",
    "error_code": "ABSENT_SUBSCRIBER",
    "error_reason": "Handset unreachable or switched off",
    "failed_at": "2026-10-28T16:10:05.400Z"
  }
}

import crypto from 'crypto';
import express from 'express';

const app = express();

// Capture the raw body for exact HMAC verification
app.post('/webhooks/ugatext', express.raw({ type: 'application/json' }), (req, res) => {
  const sigHeader = req.headers['x-ugatext-signature'];
  const secret = process.env.UGATEXT_WEBHOOK_SECRET; // "whsec_..."

  if (!sigHeader || !secret) {
    return res.status(401).send('Missing signature or secret');
  }

  const parts = Object.fromEntries(
    sigHeader.split(',').map((part) => part.split('='))
  );
  const timestamp = parts.t;
  const receivedSig = parts.v1;

  const rawBody = req.body.toString('utf8');
  const signedPayload = `${timestamp}.${rawBody}`;

  const expectedSig = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  const isValid = crypto.timingSafeEqual(
    Buffer.from(receivedSig, 'hex'),
    Buffer.from(expectedSig, 'hex')
  );

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

  const event = JSON.parse(rawBody);
  console.log('Verified UgaText event:', event.event, event.data);
  res.status(200).json({ received: true });
});

import hmac
import hashlib

def verify_ugatext_webhook(raw_body: bytes, sig_header: str, secret: str) -> bool:
    parts = dict(item.split("=", 1) for item in sig_header.split(",") if "=" in item)
    timestamp = parts.get("t", "")
    received_sig = parts.get("v1", "")

    signed_payload = f"{timestamp}.{raw_body.decode('utf-8')}".encode("utf-8")
    expected_sig = hmac.new(
        secret.encode("utf-8"),
        signed_payload,
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(received_sig, expected_sig)