Transactional Email Webhook API

Verifying Webhooks

Every webhook is HMAC-SHA256 signed using your webhook secret. Verify the signature before trusting the payload.

X-Webhook-Signature: sha256=<hex>

Python (Django / Flask / FastAPI)

import hmac
import hashlib
import time

WEBHOOK_SECRET = "whsec_your_secret_here"

def verify_webhook(request_body: bytes, timestamp: str, signature: str) -> bool:
    # 1. Reject stale requests (> 5 minutes)
    if abs(int(time.time()) - int(timestamp)) > 300:
        return False

    # 2. Verify HMAC-SHA256(timestamp.body)
    signed = f"{timestamp}.".encode() + request_body
    expected = "sha256=" + hmac.new(
        WEBHOOK_SECRET.encode(),
        signed,
        hashlib.sha256,
    ).hexdigest()

    return hmac.compare_digest(signature, expected)


# Django view example
from django.views.decorators.csrf import csrf_exempt
from rest_framework.decorators import api_view, permission_classes
from rest_framework.permissions import AllowAny
from rest_framework.response import Response

@csrf_exempt
@api_view(["POST"])
@permission_classes([AllowAny])
def webhook_receiver(request):
    body = request.body
    timestamp = request.headers.get("X-Webhook-Timestamp")
    signature = request.headers.get("X-Webhook-Signature")

    if not verify_webhook(body, timestamp, signature):
        return Response({"error": "invalid signature"}, status=401)

    # Parse and use the email
    email = request.data
    sender = email["from"]
    subject = email["subject"]
    forwarder = email.get("forwarder")  # only present for SRS mail

    # Your business logic here
    # e.g.: match reference numbers, update orders, send notifications

    return Response({"status": "ok"})

Go (net/http)

package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "encoding/json"
    "io"
    "log"
    "net/http"
    "os"
    "strconv"
    "time"
)

var webhookSecret = os.Getenv("WEBHOOK_SECRET")

type EmailWebhook struct {
    MessageID string  `json:"message_id"`
    From      string  `json:"from"`
    Forwarder *string `json:"forwarder,omitempty"`
    To        []string `json:"to"`
    Subject   string  `json:"subject"`
    Body      string  `json:"body"`
}

func handleWebhook(w http.ResponseWriter, r *http.Request) {
    rawBody, _ := io.ReadAll(r.Body)
    timestamp := r.Header.Get("X-Webhook-Timestamp")
    sigHeader := r.Header.Get("X-Webhook-Signature")

    ts, _ := strconv.ParseInt(timestamp, 10, 64)
    if time.Now().Unix()-ts > 300 {
        http.Error(w, "timestamp too old", http.StatusBadRequest)
        return
    }

    mac := hmac.New(sha256.New, []byte(webhookSecret))
    mac.Write([]byte(timestamp + "."))
    mac.Write(rawBody)
    expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))

    if !hmac.Equal([]byte(sigHeader), []byte(expected)) {
        http.Error(w, "invalid signature", http.StatusUnauthorized)
        return
    }

    var email EmailWebhook
    json.Unmarshal(rawBody, &email)

    log.Printf("Received: %s from %s", email.Subject, email.From)
    if email.Forwarder != nil {
        log.Printf("Forwarded via: %s", *email.Forwarder)
    }

    w.WriteHeader(http.StatusOK)
    w.Write([]byte(`{"status":"ok"}`))
}

JavaScript (Express)

const crypto = require("crypto");
const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

app.post("/webhook", express.json({
  verify: (req, _res, buf) => { req.rawBody = buf; }
}), (req, res) => {
  const timestamp = req.headers["x-webhook-timestamp"];
  const sigHeader = req.headers["x-webhook-signature"];
  const rawBody = req.rawBody;

  // 1. Reject stale requests (> 5 min)
  if (Math.floor(Date.now() / 1000) - parseInt(timestamp) > 300) {
    return res.status(400).json({ error: "timestamp too old" });
  }

  // 2. Verify HMAC-SHA256(timestamp.body)
  const expected = "sha256=" + crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  if (!crypto.timingSafeEqual(
    Buffer.from(sigHeader), Buffer.from(expected)
  )) {
    return res.status(401).json({ error: "invalid signature" });
  }

  // 3. Use the email
  const { from, forwarder, subject, body } = req.body;
  console.log(`Received: ${subject} from ${from}`);
  if (forwarder) console.log(`Forwarded via: ${forwarder}`);

  res.json({ status: "ok" });
});