{
  "event": "collection.completed",
  "timestamp": "2026-03-24T14:30:00Z",
  "data": {
    "id": "txn_abc123",
    "status": "successful",
    "amount": 50000,
    "currency": "UGX",
    "provider": "mtn",
    "phone_number": "256771234567",
    "description": "Order #1234",
    "metadata": {
      "order_id": "order_1234",
      "customer_email": "customer@example.com"
    },
    "created_at": "2026-03-24T14:29:50Z",
    "completed_at": "2026-03-24T14:30:00Z"
  }
}

import crypto from "crypto";
 
function verifyWebhookSignature(
  rawBody: string, // The raw request body as a string
  signature: string, // From X-DGateway-Signature header
  secret: string, // Your webhook secret
): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
 
  // Use timingSafeEqual to prevent timing attacks
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}
 
// Usage in Next.js App Router
export async function POST(req: NextRequest) {
  const rawBody = await req.text();
  const signature = req.headers.get("x-dgateway-signature") || "";
 
  if (
    !verifyWebhookSignature(
      rawBody,
      signature,
      process.env.DGATEWAY_WEBHOOK_SECRET!,
    )
  ) {
    return NextResponse.json({ error: "Invalid signature" }, { status: 401 });
  }
 
  // Safe to process
  const payload = JSON.parse(rawBody);
  // ...
}

package webhook
 
import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
)
 
func VerifySignature(payload []byte, signature, secret string) bool {
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write(payload)
	expected := hex.EncodeToString(mac.Sum(nil))
 
	// hmac.Equal is constant-time comparison (safe against timing attacks)
	return hmac.Equal([]byte(signature), []byte(expected))
}
 
// Usage in Gin handler
func WebhookHandler(c *gin.Context) {
	body, err := io.ReadAll(c.Request.Body)
	if err != nil {
		c.JSON(400, gin.H{"error": "Bad request"})
		return
	}
 
	signature := c.GetHeader("X-DGateway-Signature")
	secret := os.Getenv("DGATEWAY_WEBHOOK_SECRET")
 
	if !VerifySignature(body, signature, secret) {
		c.JSON(401, gin.H{"error": "Invalid signature"})
		return
	}
 
	// Safe to process
	var payload WebhookPayload
	json.Unmarshal(body, &payload)
	// ...
 
	c.JSON(200, gin.H{"received": true})
}

import hmac
import hashlib
 
def verify_webhook_signature(
    raw_body: bytes,     # The raw request body
    signature: str,      # From X-DGateway-Signature header
    secret: str          # Your webhook secret
) -> bool:
    expected = hmac.new(
        secret.encode("utf-8"),
        raw_body,
        hashlib.sha256
    ).hexdigest()
 
    # compare_digest is constant-time (safe against timing attacks)
    return hmac.compare_digest(signature, expected)
 
# Usage in Flask
@app.route("/webhooks/dgateway", methods=["POST"])
def handle_webhook():
    signature = request.headers.get("X-DGateway-Signature", "")
    secret = os.getenv("DGATEWAY_WEBHOOK_SECRET")
 
    if not verify_webhook_signature(request.data, signature, secret):
        return jsonify({"error": "Invalid signature"}), 401
 
    payload = request.get_json()
    # Safe to process...
    return jsonify({"received": True}), 200

function verifyWebhookSignature(
    string $rawBody,
    string $signature,
    string $secret
): bool {
    $expected = hash_hmac('sha256', $rawBody, $secret);
    return hash_equals($expected, $signature);
}
 
// Usage
$rawBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_DGATEWAY_SIGNATURE'] ?? '';
$secret = getenv('DGATEWAY_WEBHOOK_SECRET');
 
if (!verifyWebhookSignature($rawBody, $signature, $secret)) {
    http_response_code(401);
    echo json_encode(['error' => 'Invalid signature']);
    exit;
}
 
$payload = json_decode($rawBody, true);
// Safe to process...

// app/api/webhooks/dgateway/route.ts
import { NextRequest, NextResponse } from "next/server";
import crypto from "crypto";
import { prisma } from "@/lib/prisma";
 
function verifySignature(
  payload: string,
  signature: string,
  secret: string,
): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}
 
export async function POST(req: NextRequest) {
  // Step 1: Read raw body
  const rawBody = await req.text();
  const signature = req.headers.get("x-dgateway-signature") || "";
 
  // Step 2: Verify signature
  if (
    !verifySignature(rawBody, signature, process.env.DGATEWAY_WEBHOOK_SECRET!)
  ) {
    console.error("Webhook signature verification failed");
    return NextResponse.json({ error: "Invalid signature" }, { status: 401 });
  }
 
  const { event, data, timestamp } = JSON.parse(rawBody);
 
  // Step 3: Idempotency check
  const existingLog = await prisma.webhookLog.findUnique({
    where: { transactionId_event: { transactionId: data.id, event } },
  });
 
  if (existingLog) {
    console.log(`Duplicate webhook: ${event} for ${data.id}`);
    return NextResponse.json({ received: true, duplicate: true });
  }
 
  // Step 4: Log the webhook (before processing)
  await prisma.webhookLog.create({
    data: {
      transactionId: data.id,
      event,
      payload: JSON.parse(rawBody),
      receivedAt: new Date(),
    },
  });
 
  // Step 5: Process based on event type
  try {
    switch (event) {
      case "collection.completed":
        await handleCollectionCompleted(data);
        break;
      case "collection.failed":
        await handleCollectionFailed(data);
        break;
      case "collection.expired":
        await handleCollectionExpired(data);
        break;
      case "disbursement.completed":
        await handleDisbursementCompleted(data);
        break;
      case "subscription.renewed":
        await handleSubscriptionRenewed(data);
        break;
      default:
        console.log(`Unhandled event: ${event}`);
    }
  } catch (error) {
    console.error(`Error processing webhook ${event}:`, error);
    // Still return 200 — we logged the event and can reprocess later
  }
 
  // Step 6: Return 200 immediately
  return NextResponse.json({ received: true });
}
 
async function handleCollectionCompleted(data: any) {
  if (data.status !== "successful") return;
 
  const orderId = data.metadata?.order_id;
  if (!orderId) return;
 
  // Update order status
  await prisma.order.update({
    where: { id: orderId },
    data: {
      status: "paid",
      paidAt: new Date(data.completed_at),
      transactionId: data.id,
      paymentProvider: data.provider,
      amountPaid: data.amount,
      currency: data.currency,
    },
  });
 
  // Send confirmation email (async — do not block the webhook)
  await sendOrderConfirmationEmail(orderId);
}
 
async function handleCollectionFailed(data: any) {
  const orderId = data.metadata?.order_id;
  if (!orderId) return;
 
  await prisma.order.update({
    where: { id: orderId },
    data: { status: "payment_failed" },
  });
}
 
async function handleCollectionExpired(data: any) {
  const orderId = data.metadata?.order_id;
  if (!orderId) return;
 
  await prisma.order.update({
    where: { id: orderId },
    data: { status: "expired" },
  });
}

// routes/webhooks.ts
import express from "express";
import crypto from "crypto";
import { db } from "../lib/db";
import { Queue } from "bullmq";
 
const router = express.Router();
const webhookQueue = new Queue("webhook-processing");
 
// Important: Use express.raw() to get the raw body for signature verification
router.post(
  "/dgateway",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    const signature = req.headers["x-dgateway-signature"] as string;
    const rawBody = req.body.toString();
 
    // Verify signature
    const expected = crypto
      .createHmac("sha256", process.env.DGATEWAY_WEBHOOK_SECRET!)
      .update(rawBody)
      .digest("hex");
 
    if (
      !crypto.timingSafeEqual(
        Buffer.from(signature || ""),
        Buffer.from(expected),
      )
    ) {
      return res.status(401).json({ error: "Invalid signature" });
    }
 
    const payload = JSON.parse(rawBody);
 
    // Check for duplicates
    const existing = await db.webhookLog.findFirst({
      where: { transactionId: payload.data.id, event: payload.event },
    });
 
    if (existing) {
      return res.status(200).json({ received: true, duplicate: true });
    }
 
    // Log immediately
    await db.webhookLog.create({
      data: {
        transactionId: payload.data.id,
        event: payload.event,
        payload: payload,
      },
    });
 
    // Queue for async processing (return 200 fast)
    await webhookQueue.add("process-webhook", payload);
 
    res.status(200).json({ received: true });
  },
);
 
export default router;

package handlers
 
import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"encoding/json"
	"io"
	"log"
	"net/http"
	"os"
	"time"
 
	"github.com/gin-gonic/gin"
	"gorm.io/gorm"
)
 
type WebhookPayload struct {
	Event     string          `json:"event"`
	Timestamp time.Time       `json:"timestamp"`
	Data      json.RawMessage `json:"data"`
}
 
type TransactionData struct {
	ID          string            `json:"id"`
	Status      string            `json:"status"`
	Amount      int               `json:"amount"`
	Currency    string            `json:"currency"`
	Provider    string            `json:"provider"`
	PhoneNumber string            `json:"phone_number"`
	Description string            `json:"description"`
	Metadata    map[string]string `json:"metadata"`
	CreatedAt   time.Time         `json:"created_at"`
	CompletedAt *time.Time        `json:"completed_at"`
}
 
type WebhookLog struct {
	ID            uint            `gorm:"primaryKey"`
	TransactionID string          `gorm:"uniqueIndex:idx_txn_event"`
	Event         string          `gorm:"uniqueIndex:idx_txn_event"`
	Payload       json.RawMessage `gorm:"type:jsonb"`
	ProcessedAt   *time.Time
	CreatedAt     time.Time
}
 
type WebhookHandler struct {
	db *gorm.DB
}
 
func NewWebhookHandler(db *gorm.DB) *WebhookHandler {
	return &WebhookHandler{db: db}
}
 
func (h *WebhookHandler) HandleWebhook(c *gin.Context) {
	// Read raw body
	body, err := io.ReadAll(c.Request.Body)
	if err != nil {
		c.JSON(http.StatusBadRequest, gin.H{"error": "Cannot read body"})
		return
	}
 
	// Verify signature
	signature := c.GetHeader("X-DGateway-Signature")
	secret := os.Getenv("DGATEWAY_WEBHOOK_SECRET")
 
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write(body)
	expected := hex.EncodeToString(mac.Sum(nil))
 
	if !hmac.Equal([]byte(signature), []byte(expected)) {
		c.JSON(http.StatusUnauthorized, gin.H{"error": "Invalid signature"})
		return
	}
 
	// Parse payload
	var payload WebhookPayload
	if err := json.Unmarshal(body, &payload); err != nil {
		c.JSON(http.StatusBadRequest, gin.H{"error": "Invalid JSON"})
		return
	}
 
	var txnData TransactionData
	json.Unmarshal(payload.Data, &txnData)
 
	// Idempotency check
	var existingLog WebhookLog
	result := h.db.Where("transaction_id = ? AND event = ?", txnData.ID, payload.Event).First(&existingLog)
	if result.Error == nil {
		c.JSON(http.StatusOK, gin.H{"received": true, "duplicate": true})
		return
	}
 
	// Log the webhook
	h.db.Create(&WebhookLog{
		TransactionID: txnData.ID,
		Event:         payload.Event,
		Payload:       body,
	})
 
	// Process the event
	switch payload.Event {
	case "collection.completed":
		h.handleCollectionCompleted(txnData)
	case "collection.failed":
		h.handleCollectionFailed(txnData)
	case "disbursement.completed":
		h.handleDisbursementCompleted(txnData)
	default:
		log.Printf("Unhandled webhook event: %s", payload.Event)
	}
 
	c.JSON(http.StatusOK, gin.H{"received": true})
}
 
func (h *WebhookHandler) handleCollectionCompleted(data TransactionData) {
	if data.Status != "successful" {
		return
	}
 
	orderID := data.Metadata["order_id"]
	if orderID == "" {
		return
	}
 
	h.db.Model(&Order{}).Where("id = ?", orderID).Updates(map[string]interface{}{
		"status":           "paid",
		"paid_at":          data.CompletedAt,
		"transaction_id":   data.ID,
		"payment_provider": data.Provider,
		"amount_paid":      data.Amount,
		"currency":         data.Currency,
	})
}

-- Webhook log table (PostgreSQL)
CREATE TABLE webhook_logs (
    id SERIAL PRIMARY KEY,
    transaction_id VARCHAR(255) NOT NULL,
    event VARCHAR(100) NOT NULL,
    payload JSONB NOT NULL,
    processed_at TIMESTAMP,
    created_at TIMESTAMP DEFAULT NOW(),
    UNIQUE(transaction_id, event)  -- Prevents duplicate processing
);

// Check-and-insert pattern with a unique constraint
async function processWebhookIdempotently(
  event: string,
  data: TransactionData,
) {
  try {
    // This will throw if the unique constraint is violated (duplicate)
    await prisma.webhookLog.create({
      data: {
        transactionId: data.id,
        event: event,
        payload: data as any,
      },
    });
  } catch (error: any) {
    if (error.code === "P2002") {
      // Unique constraint violation — this is a duplicate
      console.log(`Duplicate webhook: ${event} for ${data.id}, skipping`);
      return;
    }
    throw error; // Re-throw unexpected errors
  }
 
  // First time seeing this event — process it
  switch (event) {
    case "collection.completed":
      await fulfillOrder(data.metadata.order_id);
      break;
    // ... other events
  }
 
  // Mark as processed
  await prisma.webhookLog.update({
    where: { transactionId_event: { transactionId: data.id, event } },
    data: { processedAt: new Date() },
  });
}

import Redis from "ioredis";
 
const redis = new Redis(process.env.REDIS_URL);
 
async function isWebhookProcessed(
  transactionId: string,
  event: string,
): Promise<boolean> {
  const key = `webhook:${transactionId}:${event}`;
 
  // SET with NX (only set if not exists) and EX (expire after 7 days)
  const result = await redis.set(key, "1", "EX", 7 * 24 * 60 * 60, "NX");
 
  // Returns "OK" if the key was set (first time), null if it already existed (duplicate)
  return result === null;
}
 
// Usage
if (await isWebhookProcessed(data.id, event)) {
  console.log("Duplicate webhook, skipping");
  return;
}
 
// Process the webhook...

// Webhook handler — fast, returns 200 immediately
export async function POST(req: NextRequest) {
  const rawBody = await req.text();
  const signature = req.headers.get("x-dgateway-signature") || "";
 
  if (
    !verifySignature(rawBody, signature, process.env.DGATEWAY_WEBHOOK_SECRET!)
  ) {
    return NextResponse.json({ error: "Invalid signature" }, { status: 401 });
  }
 
  const payload = JSON.parse(rawBody);
 
  // Store the raw event
  await prisma.webhookLog.create({
    data: {
      transactionId: payload.data.id,
      event: payload.event,
      payload: payload,
      status: "received",
    },
  });
 
  // Queue for async processing
  await webhookQueue.add("process", {
    logId: payload.data.id,
    event: payload.event,
    data: payload.data,
  });
 
  // Return 200 immediately — total time: ~50ms
  return NextResponse.json({ received: true });
}
 
// Background worker — processes the event asynchronously
webhookQueue.process("process", async (job) => {
  const { logId, event, data } = job.data;
 
  try {
    switch (event) {
      case "collection.completed":
        await fulfillOrder(data.metadata.order_id);
        await sendConfirmationEmail(data.metadata.customer_email);
        await updateAnalytics(data);
        break;
      // ... other events
    }
 
    // Mark as processed
    await prisma.webhookLog.update({
      where: { transactionId: logId },
      data: { status: "processed", processedAt: new Date() },
    });
  } catch (error) {
    // Mark as failed — can retry manually from dashboard
    await prisma.webhookLog.update({
      where: { transactionId: logId },
      data: { status: "processing_failed", error: error.message },
    });
  }
});

# macOS
brew install ngrok
 
# Windows
choco install ngrok
 
# Or download from https://ngrok.com/download

cd my-app
npm run dev
# Server running on http://localhost:3000

ngrok http 3000

curl -X POST https://api.dgateway.io/v1/collections \
  -H "Authorization: Bearer dg_test_sk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "UGX",
    "phone_number": "256771000001",
    "provider": "mtn",
    "description": "Test with ngrok",
    "callback_url": "https://a1b2c3d4.ngrok.io/api/webhooks/dgateway"
  }'