Verify webhook requests

Every webhook request includes an X-Arowana-Signature header. Always verify it before processing the payload to ensure the request came from Arowana and wasn’t tampered with.

How it works

Read the raw request body

Use the exact HTTP body bytes. Do not parse and re-serialize JSON before verifying — this changes the byte sequence and breaks the signature.

Compute HMAC-SHA256

Sign the raw body bytes with your webhook secret using HMAC-SHA256. The expected value is sha256= followed by the hex digest.

Compare with constant-time equality

Use a constant-time comparison to prevent timing attacks. Return 401 on mismatch — do not process the payload.

Implementation

const crypto = require("crypto");
const express = require("express");

function verifySignature(rawBody, secret, signature) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

app.post(
  "/webhooks/arowana",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const sig = req.headers["x-arowana-signature"];
    if (!verifySignature(req.body, process.env.WEBHOOK_SECRET, sig)) {
      return res.status(401).send("Invalid signature");
    }

    const event = JSON.parse(req.body.toString());
    res.status(200).send("OK");
  }
);

Do not use express.json() on the webhook route. The middleware parses the body before you can verify the raw bytes.

import hmac
import hashlib
import os
from flask import Flask, request, abort

app = Flask(__name__)

@app.route("/webhooks/arowana", methods=["POST"])
def webhook():
    raw_body = request.get_data()
    signature = request.headers.get("X-Arowana-Signature", "")
    secret = os.environ["WEBHOOK_SECRET"]

    expected = "sha256=" + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected, signature):
        abort(401)

    event = request.get_json(force=True)
    return "OK", 200

package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/hex"
	"io"
	"net/http"
	"os"
)

func verifySignature(body []byte, secret, signature string) bool {
	mac := hmac.New(sha256.New, []byte(secret))
	mac.Write(body)
	expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))
	return hmac.Equal([]byte(expected), []byte(signature))
}

func webhookHandler(w http.ResponseWriter, r *http.Request) {
	body, err := io.ReadAll(r.Body)
	if err != nil {
		http.Error(w, "Bad request", http.StatusBadRequest)
		return
	}

	sig := r.Header.Get("X-Arowana-Signature")
	if !verifySignature(body, os.Getenv("WEBHOOK_SECRET"), sig) {
		http.Error(w, "Invalid signature", http.StatusUnauthorized)
		return
	}

	w.WriteHeader(http.StatusOK)
	w.Write([]byte("OK"))
}

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

require "sinatra"
require "openssl"
require "json"

post "/webhooks/arowana" do
  raw_body = request.body.read
  signature = request.env["HTTP_X_AROWANA_SIGNATURE"] || ""
  secret = ENV.fetch("WEBHOOK_SECRET")

  digest = OpenSSL::HMAC.hexdigest("SHA256", secret, raw_body)
  expected = "sha256=#{digest}"

  unless Rack::Utils.secure_compare(expected, signature)
    halt 401, "Invalid signature"
  end

  event = JSON.parse(raw_body)
  status 200
  "OK"
end

<?php

$rawBody   = file_get_contents("php://input");
$signature = $_SERVER["HTTP_X_AROWANA_SIGNATURE"] ?? "";
$secret    = getenv("WEBHOOK_SECRET");

$expected = "sha256=" . hash_hmac("sha256", $rawBody, $secret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    echo "Invalid signature";
    exit;
}

$event = json_decode($rawBody, true);
http_response_code(200);
echo "OK";

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import jakarta.servlet.http.*;
import java.security.MessageDigest;

public class WebhookServlet extends HttpServlet {

    @Override
    protected void doPost(HttpServletRequest req, HttpServletResponse resp)
            throws Exception {

        byte[] body = req.getInputStream().readAllBytes();
        String signature = req.getHeader("X-Arowana-Signature");
        String secret = System.getenv("WEBHOOK_SECRET");

        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(secret.getBytes(), "HmacSHA256"));
        byte[] hash = mac.doFinal(body);

        StringBuilder hex = new StringBuilder("sha256=");
        for (byte b : hash) hex.append(String.format("%02x", b));
        String expected = hex.toString();

        if (!MessageDigest.isEqual(
                expected.getBytes(), signature.getBytes())) {
            resp.sendError(401, "Invalid signature");
            return;
        }

        resp.setStatus(200);
        resp.getWriter().write("OK");
    }
}

Webhooks

RCS

Email

Contacts

Billing

SMS

Verify webhook requests

How it works

Implementation

Webhooks

RCS

Email

Contacts

Billing

SMS

​How it works

​Implementation

How it works

Implementation