Verify webhook signatures in Python and Go

The Webhook security page covers the full signature protocol — header formats, the signed string, and timing-safe comparison. But its polished examples are mostly Node.js. If your backend is Python or Go with no Node in the request path, you need a canonical verifier you can paste directly into your codebase and run with just the standard library. This guide gives you exactly that: one complete, copy-pasteable HMAC verifier per language. Each handles the header trio (X-Orbit-Signature first, X-Orbit-Signature-Next during a rotation, X-Devotel-Signature as the legacy fallback), guards the replay window, and compares with a timing-safe function. Each also ships with a negative test that proves the verifier refuses a wrong secret. For the protocol details — what each header carries, the <t>.<raw_body> signed string, rotation grace windows — see Webhook security. For a full receiver walkthrough with a queue and retry logic, see Build a durable webhook consumer.

What you’re verifying

Every delivery carries the signature in up to three headers. Your verifier should read them in this order and accept if any matches:

X-Orbit-Signature — canonical, signed with your current secret. Check this first.
X-Orbit-Signature-Next — only present during a key-rotation grace window, signed with your previous secret. If you hold both secrets during a rotation, try this after the first fails.
X-Devotel-Signature — legacy back-compat header that carries one or two v1= candidates in a single header (new then previous). Old deliveries queued before the canonical headers existed carry only this one.

Each header uses the same encoding: t=<unix_seconds>,v1=<hex> with an optional second v1= in the legacy header. The signed string is <t>.<raw_body> — the literal timestamp from the header, a dot, then the exact bytes of the request body.

Prerequisites

Your webhook signing secret (whsec_...), captured at endpoint creation via POST /api/v1/webhooks or after a rotation via POST /api/v1/webhooks/{id}/rotate-secret. If you only have a masked preview (whsec_********...<last4>), rotate to recover a usable secret — the preview never validates.
A webhook endpoint that receives the raw request body before any JSON parser or middleware touches it (see Step 1 below).

Step 1 — Preserve the raw body

HMAC is computed over the exact bytes Orbit POSTed. If your framework deserializes the body first (request.get_json(), json.NewDecoder(r.Body) on the same body stream, an auto-parsing middleware), whatever you re-serialize will differ from what was signed. Preserve the raw bytes and pass them to the verifier. Python (Flask): use request.data (bytes) — do not call request.get_json() before verification. Go (net/http): read r.Body into a []byte once, then use that buffer for both signature verification and JSON decoding.

# Flask — read raw body once
@app.route("/webhooks/orbit", methods=["POST"])
def handle():
    raw = request.data  # bytes; untouched by any parser
    ...

// net/http — read body once, reuse for verify and JSON
rawBody, err := io.ReadAll(r.Body)
if err != nil {
    http.Error(w, "read error", http.StatusBadRequest)
    return
}

Step 2 — Python verifier (stdlib `hmac` + `hashlib`)

This is the complete verifier. Drop it into any Python codebase — no external dependencies.

import hashlib
import hmac
import time
from typing import Optional


def parse_signature_header(header: str):
    """Split a header like 't=123,v1=abc,v1=def' into (t, [v1s])."""
    t: Optional[str] = None
    v1s: list[str] = []
    for part in header.split(","):
        part = part.strip()
        if "=" not in part:
            continue
        key, _, value = part.partition("=")
        if key == "t":
            t = value
        elif key == "v1":
            v1s.append(value)
    return t, v1s


def verify_webhook_signature(raw_body: bytes, header: Optional[str], secret: str) -> bool:
    """Return True if any v1 candidate matches the HMAC-SHA256 of '<t>.<raw_body>'."""
    if not header:
        return False
    t, v1s = parse_signature_header(header)
    if not t or not v1s:
        return False

    # Replay guard: reject timestamps older than 5 minutes.
    try:
        age = int(time.time()) - int(t)
    except ValueError:
        return False
    if age < 0 or age > 5 * 60:
        return False

    signed = f"{t}.".encode("utf-8") + raw_body
    expected = hmac.new(secret.encode("utf-8"), signed, hashlib.sha256).hexdigest()

    # Timing-safe against every v1 candidate (covers rotation grace).
    return any(hmac.compare_digest(candidate, expected) for candidate in v1s)

Flask handler:

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/webhooks/orbit", methods=["POST"])
def handle_webhook():
    # Read headers in canonical → next → legacy order.
    header = (
        request.headers.get("X-Orbit-Signature")
        or request.headers.get("X-Orbit-Signature-Next")
        or request.headers.get("X-Devotel-Signature")
    )
    if not verify_webhook_signature(request.data, header, "whsec_your_secret"):
        return jsonify({"error": "Invalid signature"}), 401

    event = request.get_json()  # safe to parse after verification
    # Process the event...
    return jsonify({"received": True}), 200

Step 3 — Go verifier (`crypto/hmac`)

Standard library only. Works with net/http, Gin, Echo, or any framework.

package webhook

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"strconv"
	"strings"
	"time"
)

func parseSignatureHeader(header string) (string, []string) {
	var t string
	var v1s []string
	for _, part := range strings.Split(header, ",") {
		part = strings.TrimSpace(part)
		eq := strings.IndexByte(part, '=')
		if eq < 0 {
			continue
		}
		key, value := part[:eq], part[eq+1:]
		switch key {
		case "t":
			t = value
		case "v1":
			v1s = append(v1s, value)
		}
	}
	return t, v1s
}

// VerifySignature returns true if any v1 candidate matches the HMAC-SHA256
// of "<t>.<rawBody>". It rejects malformed or stale (>5 min) signatures.
func VerifySignature(rawBody []byte, header, secret string) bool {
	t, v1s := parseSignatureHeader(header)
	if t == "" || len(v1s) == 0 {
		return false
	}
	ts, err := strconv.ParseInt(t, 10, 64)
	if err != nil {
		return false
	}
	age := time.Now().Unix() - ts
	if age < 0 || age > 5*60 {
		return false
	}

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

	for _, candidate := range v1s {
		if hmac.Equal([]byte(candidate), []byte(expected)) {
			return true
		}
	}
	return false
}

net/http handler:

package main

import (
	"encoding/json"
	"io"
	"net/http"
	"os"
)

func handler(w http.ResponseWriter, r *http.Request) {
	rawBody, err := io.ReadAll(r.Body)
	if err != nil {
		http.Error(w, "read error", http.StatusBadRequest)
		return
	}

	// Canonical → next → legacy.
	header := r.Header.Get("X-Orbit-Signature")
	if header == "" {
		header = r.Header.Get("X-Orbit-Signature-Next")
	}
	if header == "" {
		header = r.Header.Get("X-Devotel-Signature")
	}

	if !webhook.VerifySignature(rawBody, header, os.Getenv("ORBIT_WEBHOOK_SECRET")) {
		http.Error(w, `{"error":"Invalid signature"}`, http.StatusUnauthorized)
		return
	}

	var event map[string]interface{}
	if err := json.Unmarshal(rawBody, &event); err != nil {
		http.Error(w, "bad json", http.StatusBadRequest)
		return
	}
	// Process the event...
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(http.StatusOK)
	json.NewEncoder(w).Encode(map[string]bool{"received": true})
}

func main() {
	http.HandleFunc("/webhooks/orbit", handler)
	http.ListenAndServe(":8080", nil)
}

Step 4 — Negative test: prove reject-on-wrong-secret

A verifier that always returns true (or never actually compares) is worse than no verifier. Test the negative path once in unit tests and once against a live delivery with the wrong secret.

Python pytest

def test_rejects_wrong_secret():
    body = b'{"id":"evt_1","type":"message.delivered"}'
    t = str(int(time.time()))
    # Build a valid-looking header but signed with a different secret.
    signed = f"{t}.".encode() + body
    bad_sig = hmac.new(b"whsec_wrong", signed, hashlib.sha256).hexdigest()
    header = f"t={t},v1={bad_sig}"

    assert not verify_webhook_signature(body, header, "whsec_correct")


def test_rejects_missing_header():
    body = b'{"id":"evt_1"}'
    assert not verify_webhook_signature(body, None, "whsec_correct")
    assert not verify_webhook_signature(body, "", "whsec_correct")

Go `testing`

func TestRejectsWrongSecret(t *testing.T) {
	body := []byte(`{"id":"evt_1","type":"message.delivered"}`)
	ts := strconv.FormatInt(time.Now().Unix(), 10)
	mac := hmac.New(sha256.New, []byte("whsec_wrong"))
	mac.Write([]byte(ts + "."))
	mac.Write(body)
	header := "t=" + ts + ",v1=" + hex.EncodeToString(mac.Sum(nil))

	if VerifySignature(body, header, "whsec_correct") {
		t.Fatal("verifier accepted a signature built with the wrong secret")
	}
}

func TestRejectsMissingHeader(t *testing.T) {
	body := []byte(`{"id":"evt_1"}`)
	if VerifySignature(body, "", "whsec_correct") {
		t.Fatal("verifier accepted a missing header")
	}
}

Run these before deploying. If a “reject” test passes (the verifier returns true on garbage), you have a logic bug — fix it before shipping.

Rotation: handling `X-Orbit-Signature-Next`

During a secret rotation grace window (7 days), every delivery carries both the canonical header (signed with the new secret) and X-Orbit-Signature-Next (signed with the previous secret). Your verifier should keep both secrets configured and try both headers:

Try X-Orbit-Signature against the current secret.
If that fails and X-Orbit-Signature-Next is present, try it against the previous secret.
Accept if either matches.

The header-order code in the handlers above already falls back to X-Orbit-Signature-Next. To verify against both secrets, keep both in your config and try each:

def verify_with_rotation(raw_body: bytes, headers, current_secret: str, prev_secret: Optional[str]) -> bool:
    primary = headers.get("X-Orbit-Signature") or headers.get("X-Devotel-Signature", "")
    if primary and verify_webhook_signature(raw_body, primary, current_secret):
        return True
    next_header = headers.get("X-Orbit-Signature-Next")
    if prev_secret and next_header:
        return verify_webhook_signature(raw_body, next_header, prev_secret)
    return False

After the grace window ends, Orbit stops sending X-Orbit-Signature-Next and the previous secret retires. Remove it from your config.

Troubleshooting

If a delivery you believe is valid fails:

Raw body mutated — a body parser ran before verification (see Step 1). See Troubleshooting: signature failures section 1 and 5.
Wrong secret — a masked whsec_********...<last4> preview copied in, or a rotation that didn’t reach your code. See Webhook security: signing secret.
Stale timestamp — your server clock is skewed by more than 5 minutes. See Troubleshooting: signature failures section 3.
Missing header — check the fallback order (canonical → next → legacy). Old queued deliveries may only have X-Devotel-Signature.

For the full failure catalog mapped to error codes, see Troubleshooting: signature verification failures.

Continue

Webhook security — full protocol spec and all header details
Build a durable webhook consumer — queue, dedupe, ack-fast pattern
Troubleshooting: signature failures — complete failure catalog
Webhook events — event catalog

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

Verify webhook signatures in Python and Go

Verify webhook signatures in Python and Go

What you’re verifying

Prerequisites

Step 1 — Preserve the raw body

Step 2 — Python verifier (stdlib `hmac` + `hashlib`)

Step 3 — Go verifier (`crypto/hmac`)

Step 4 — Negative test: prove reject-on-wrong-secret

Python pytest

Go `testing`

Rotation: handling `X-Orbit-Signature-Next`

Troubleshooting

Continue

​Verify webhook signatures in Python and Go

​What you’re verifying

​Prerequisites

​Step 1 — Preserve the raw body

​Step 2 — Python verifier (stdlib hmac + hashlib)

​Step 3 — Go verifier (crypto/hmac)

​Step 4 — Negative test: prove reject-on-wrong-secret

​Python pytest

​Go testing

​Rotation: handling X-Orbit-Signature-Next

​Troubleshooting

​Continue

Verify webhook signatures in Python and Go

What you’re verifying

Prerequisites

Step 1 — Preserve the raw body

Step 2 — Python verifier (stdlib `hmac` + `hashlib`)

Step 3 — Go verifier (`crypto/hmac`)

Step 4 — Negative test: prove reject-on-wrong-secret

Python pytest

Go `testing`

Rotation: handling `X-Orbit-Signature-Next`

Troubleshooting

Continue