Verify webhook signatures with the SDK, per language

Verifying a webhook signature is one SDK call in every language. What trips teams up is the wiring around it: reading the raw body before a JSON parser mutates it, reading the right header, and returning 401 (not 200) on a bad signature so retries don’t ack forged traffic. This page gives you a complete, working handler per language — paste it, point it at your secret, and it runs. The protocol itself (header formats, the <t>.<raw_body> signed string, rotation grace windows, timing-safe comparison) is specified on Webhook security. If you have a Python or Go backend and don’t want to pull in the SDK, the no-SDK verifiers do the same check with the standard library.

What every handler does

Read the raw body — before any JSON middleware or parser runs. HMAC is over the exact bytes Orbit POSTed; a parse-and-reserialize changes them.
Read the signature header — canonical X-Orbit-Signature first, legacy X-Devotel-Signature as fallback (old queued deliveries may carry only the legacy one). Each carries t=<unix_ts>,v1=<hex>.
Verify — one SDK call: returns the decoded event, throws on any failure (malformed header, replay-window breach, signature mismatch, invalid JSON).
Answer 401 on failure — a forged or stale request must not get 200.

Node.js (Express)

SDK: Orbit.webhooks.constructEvent(payload, signature, secret) — throws OrbitWebhookSignatureError on failure. Mount Express’s raw body parser on the webhook route only; keep your JSON parser elsewhere.

import express from 'express';
import { Orbit, OrbitWebhookSignatureError } from '@devotel-orbit/node';

const app = express();

app.post(
  '/webhooks/orbit',
  express.raw({ type: 'application/json' }), // raw bytes, not parsed JSON
  (req, res) => {
    const signature =
      (req.headers['x-orbit-signature'] as string | undefined) ??
      (req.headers['x-devotel-signature'] as string | undefined) ??
      '';
    try {
      const event = Orbit.webhooks.constructEvent(
        req.body.toString('utf8'),
        signature,
        process.env.ORBIT_WEBHOOK_SECRET!,
      );
      switch (event.type) {
        case 'message.delivered':
          // handle the event...
          break;
        default:
          break;
      }
      res.status(200).json({ received: true });
    } catch (err) {
      if (err instanceof OrbitWebhookSignatureError) {
        return res.status(401).json({ error: err.message });
      }
      throw err;
    }
  },
);

Python (Flask)

SDK: verify_webhook(payload=..., signature=..., secret=...) — keyword-only, returns the decoded event dict, raises OrbitWebhookSignatureError.

from flask import Flask, request, jsonify
from orbit_sdk import verify_webhook
from orbit_sdk.errors import OrbitWebhookSignatureError

app = Flask(__name__)

@app.route("/webhooks/orbit", methods=["POST"])
def handle_webhook():
    signature = (
        request.headers.get("X-Orbit-Signature")
        or request.headers.get("X-Devotel-Signature")
        or ""
    )
    try:
        event = verify_webhook(
            payload=request.get_data(),  # raw bytes — don't parse first
            signature=signature,
            secret="whsec_your_secret",
        )
    except OrbitWebhookSignatureError as exc:
        return jsonify({"error": str(exc)}), 401
    # handle event ...
    return jsonify({"received": True}), 200

Go (`net/http`)

SDK: orbit.VerifyWebhook(payload, signatureHeader, secret, 0, time.Time{}) — the 0 tolerance picks the default 5-minute window; the zero time.Time{} means “now”. Returns the decoded event or a *orbit.WebhookSignatureError.

package main

import (
    "io"
    "net/http"
    "time"

    orbit "github.com/devotel/orbit-go/orbit"
)

func handler(w http.ResponseWriter, r *http.Request) {
    rawBody, err := io.ReadAll(r.Body) // raw bytes; reuse for verify + JSON
    if err != nil {
        http.Error(w, "read error", http.StatusBadRequest)
        return
    }
    signature := r.Header.Get("X-Orbit-Signature")
    if signature == "" {
        signature = r.Header.Get("X-Devotel-Signature")
    }
    event, err := orbit.VerifyWebhook(
        rawBody,
        signature,
        "whsec_your_secret",
        0,            // default tolerance
        time.Time{},  // now
    )
    if err != nil {
        http.Error(w, `{"error":"invalid signature"}`, http.StatusUnauthorized)
        return
    }
    _ = event // handle the event...
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(http.StatusOK)
    w.Write([]byte(`{"received":true}`))
}

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

PHP

SDK: Webhooks::verify(payload: ..., signature: ..., secret: ...) — named arguments, returns the decoded event array, throws OrbitWebhookSignatureError.

<?php

use Devotel\Orbit\Webhooks;
use Devotel\Orbit\Errors\OrbitWebhookSignatureError;

$signature = $_SERVER['HTTP_X_ORBIT_SIGNATURE']
    ?? $_SERVER['HTTP_X_DEVOTEL_SIGNATURE']
    ?? '';

try {
    $event = Webhooks::verify(
        payload: file_get_contents('php://input'), // raw body
        signature: $signature,
        secret: getenv('ORBIT_WEBHOOK_SECRET'),
    );
} catch (OrbitWebhookSignatureError $e) {
    http_response_code(401);
    echo json_encode(['error' => $e->getMessage()]);
    exit;
}

// handle $event ...
http_response_code(200);
echo json_encode(['received' => true]);

Ruby (Sinatra)

SDK: OrbitSdk::Webhooks.verify(payload:, signature:, secret:) — keyword arguments, returns the decoded event hash, raises OrbitSdk::OrbitWebhookSignatureError.

require "sinatra"
require "orbit_sdk"

post "/webhooks/orbit" do
  signature = request.env["HTTP_X_ORBIT_SIGNATURE"] ||
              request.env["HTTP_X_DEVOTEL_SIGNATURE"] || ""
  begin
    event = OrbitSdk::Webhooks.verify(
      payload: request.body.read, # raw body
      signature: signature,
      secret: ENV["ORBIT_WEBHOOK_SECRET"]
    )
    # handle event ...
    status 200
    { received: true }.to_json
  rescue OrbitSdk::OrbitWebhookSignatureError => e
    status 401
    { error: e.message }.to_json
  end
end

Java

SDK: Webhooks.verify(payload, signature, secret) — returns the decoded event Map, throws OrbitWebhookSignatureError. The example below runs on the JDK’s built-in HttpServer; with Spring or another framework, capture the body as raw byte[]/String before any deserializer touches it.

import com.sun.net.httpserver.HttpExchange;
import com.sun.net.httpserver.HttpServer;
import io.devotel.orbit.Webhooks;
import io.devotel.orbit.errors.OrbitWebhookSignatureError;
import java.net.InetSocketAddress;
import java.nio.charset.StandardCharsets;
import java.util.Map;

public class WebhookReceiver {
    public static void main(String[] args) throws Exception {
        HttpServer server = HttpServer.create(new InetSocketAddress(8080), 0);
        server.createContext("/webhooks/orbit", WebhookReceiver::handle);
        server.start();
    }

    private static void handle(HttpExchange exchange) {
        try {
            byte[] raw = exchange.getRequestBody().readAllBytes(); // raw body
            String signature = exchange.getRequestHeaders()
                    .getFirst("X-Orbit-Signature");
            if (signature == null) {
                signature = exchange.getRequestHeaders()
                        .getFirst("X-Devotel-Signature");
            }
            try {
                Map<String, Object> event = Webhooks.verify(
                        new String(raw, StandardCharsets.UTF_8),
                        signature,
                        System.getenv("ORBIT_WEBHOOK_SECRET"));
                // handle event ...
                respond(exchange, 200, "{\"received\":true}");
            } catch (OrbitWebhookSignatureError e) {
                respond(exchange, 401, "{\"error\":\"invalid signature\"}");
            }
        } catch (Exception e) {
            respondQuiet(exchange, 500);
        }
    }

    private static void respond(HttpExchange exchange, int status, String body) throws java.io.IOException {
        byte[] bytes = body.getBytes(StandardCharsets.UTF_8);
        exchange.getResponseHeaders().set("Content-Type", "application/json");
        exchange.sendResponseHeaders(status, bytes.length);
        exchange.getResponseBody().write(bytes);
        exchange.close();
    }

    private static void respondQuiet(HttpExchange exchange, int status) {
        try {
            exchange.sendResponseHeaders(status, -1);
            exchange.close();
        } catch (java.io.IOException ignored) {}
    }
}

C# (ASP.NET minimal API)

SDK: Webhooks.Verify(payload, signature, secret) — returns the decoded event JsonElement, throws OrbitWebhookSignatureError.

using Devotel.Orbit; // Webhooks, OrbitWebhookSignatureError

var app = WebApplication.Create(args);

app.MapPost("/webhooks/orbit", async (HttpRequest request) =>
{
    using var reader = new StreamReader(request.Body);
    var payload = await reader.ReadToEndAsync(); // raw body
    var signature =
        request.Headers["X-Orbit-Signature"].FirstOrDefault()
        ?? request.Headers["X-Devotel-Signature"].FirstOrDefault()
        ?? string.Empty;
    try
    {
        var parsed = Webhooks.Verify(
            payload,
            signature,
            Environment.GetEnvironmentVariable("ORBIT_WEBHOOK_SECRET") ?? "");
        // handle parsed ...
        return Results.Json(new { received = true });
    }
    catch (OrbitWebhookSignatureError ex)
    {
        return Results.Json(
            new { error = ex.Message },
            statusCode: StatusCodes.Status401Unauthorized);
    }
});

app.Run();

Rotation and troubleshooting

During a secret rotation grace window, verify X-Orbit-Signature against the current secret and X-Orbit-Signature-Next against the previous secret — both headers arrive on every delivery until the grace window ends (7 days). The pattern per language mirrors the rotation section of the no-SDK guide. If a valid delivery still fails verification, the cause is almost always one of: a body parser ran before verification (fix per Step 1 above), a masked secret preview (whsec_********...<last4>) copied in instead of a live secret, or server clock skew past the replay window. See Troubleshooting: signature verification failures.

Continue

Webhook security — full signature protocol
Verify without the SDK (Python and Go) — stdlib verifiers
Webhook events — event catalog
Build a durable webhook consumer — queue, dedupe, ack-fast pattern

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

Verify webhook signatures with the SDK, per language

Verify webhook signatures with the SDK, per language

What every handler does

Node.js (Express)

Python (Flask)

Go (`net/http`)

PHP

Ruby (Sinatra)

Java

C# (ASP.NET minimal API)

Rotation and troubleshooting

Continue

​Verify webhook signatures with the SDK, per language

​What every handler does

​Node.js (Express)

​Python (Flask)

​Go (net/http)

​PHP

​Ruby (Sinatra)

​Java

​C# (ASP.NET minimal API)

​Rotation and troubleshooting

​Continue

Verify webhook signatures with the SDK, per language

What every handler does

Node.js (Express)

Python (Flask)

Go (`net/http`)

PHP

Ruby (Sinatra)

Java

C# (ASP.NET minimal API)

Rotation and troubleshooting

Continue