Gozem Developer DocsDocs

Back to site Go to consoleConsole Get beta accessGet access

Verify a webhook signature

Read the raw bytes, compare the HMAC in constant time, then acknowledge before doing the work.

Platform3 steps10 min

Your webhook URL is public. Anyone who finds it can post a courier.trip.completed, so check the signature before you act on anything.

It is an HMAC SHA-256 of the raw body, keyed with your webhook secret, sent in X-Webhook-Signature.

Read the raw bytes

The HMAC covers the exact bytes Gozem sent. Parse and re-encode, and your JSON writer will reorder keys or change spacing, and every signature fails.

Most frameworks discard the raw body, so ask for it explicitly.

Compare in constant time

== returns on the first differing byte. That timing difference is enough to recover a valid signature one byte at a time.

Use hmac.Equal, or timingSafeEqual in Node. Reject and return; do not log anything from a request that failed this.

Acknowledge, then work

Gozem retries if you do not return 2xx, and repeated failures disable the webhook. A handler that writes to four tables before responding will eventually look like a failure, so respond first and do the real work after.

recordEvent is your own idempotency store: it writes the guid and returns false if it was already there. Retries mean the same event arrives twice, and a unique index on that column is the whole implementation.

Before you ship

Branch on event_type and ignore ones you do not know. New types get added, and a handler that 500s on an unfamiliar one disables itself.
Return 5xx when your own storage is down. That is the one case where you want the retry.
Accept events over HTTPS only.
A gateway that rewrites bodies in transit breaks the signature. Worth checking first if it passes locally and fails on deploy.

Full event list and retry schedule: Webhooks.

import crypto from 'node:crypto';
import express from 'express';

const app = express();
const secret = process.env.GOZEM_WEBHOOK_SECRET;

// express.raw buffers the bytes instead of parsing them, scoped to this one route.
app.post('/webhooks/gozem', express.raw({ type: '*/*', limit: '1mb' }), (req, res) => {
  const raw = req.body;
  const signature = req.get('X-Webhook-Signature') ?? '';

  const want = crypto.createHmac('sha256', secret).update(raw).digest('hex');

  const a = Buffer.from(want, 'utf8');
  const b = Buffer.from(signature, 'utf8');

  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.status(401).send('invalid signature');
  }

  let event;
  try {
    event = JSON.parse(raw.toString('utf8'));
  } catch {
    return res.status(400).send('malformed payload');
  }

  // Retries mean the same event can arrive twice. Record the guid; if it was already
  // there, this delivery is a duplicate and there is nothing to do.
  if (!recordEvent(event.guid)) {
    return res.sendStatus(200);
  }

  res.sendStatus(200);
  handleEvent(event);
});

app.listen(8080);

package main

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

// Event is the envelope every Gozem webhook shares, whatever the service.
type Event struct {
    GUID      string          `json:"guid"`
    EventType string          `json:"event_type"`
    Data      json.RawMessage `json:"data"`
}

var secret = []byte(os.Getenv("GOZEM_WEBHOOK_SECRET"))

func handle(w http.ResponseWriter, r *http.Request) {
    raw, err := io.ReadAll(http.MaxBytesReader(w, r.Body, 1<<20))
    if err != nil {
        http.Error(w, "cannot read body", http.StatusBadRequest)
        return
    }
    defer r.Body.Close()

    mac := hmac.New(sha256.New, secret)
    mac.Write(raw)

    want := make([]byte, hex.EncodedLen(sha256.Size))
    hex.Encode(want, mac.Sum(nil))

    if !hmac.Equal(want, []byte(r.Header.Get("X-Webhook-Signature"))) {
        http.Error(w, "invalid signature", http.StatusUnauthorized)
        return
    }

    var event Event
    if err := json.Unmarshal(raw, &event); err != nil {
        http.Error(w, "malformed payload", http.StatusBadRequest)
        return
    }

    // Retries mean the same event can arrive twice. Record the guid; if it was
    // already there, this delivery is a duplicate and there is nothing to do.
    if !recordEvent(event.GUID) {
        w.WriteHeader(http.StatusOK)
        return
    }

    w.WriteHeader(http.StatusOK)
    go process(event)
}

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

import hashlib
import hmac
import json
import os

from flask import Flask, request

app = Flask(__name__)
secret = os.environ["GOZEM_WEBHOOK_SECRET"].encode()


@app.post("/webhooks/gozem")
def gozem_webhook():
    raw = request.get_data()
    signature = request.headers.get("X-Webhook-Signature", "")

    want = hmac.new(secret, raw, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(want, signature):
        return "invalid signature", 401

    try:
        event = json.loads(raw)
    except json.JSONDecodeError:
        return "malformed payload", 400

    # Retries mean the same event can arrive twice. Record the guid; if it was already
    # there, this delivery is a duplicate and there is nothing to do.
    if not record_event(event["guid"]):
        return "", 200

    queue.enqueue(handle_event, event)
    return "", 200

use axum::{
    body::Bytes,
    http::{HeaderMap, StatusCode},
    routing::post,
    Router,
};
use hmac::{Hmac, Mac};
use serde::Deserialize;
use sha2::Sha256;

#[derive(Deserialize)]
struct Event {
    guid: String,
    event_type: String,
}

async fn webhook(headers: HeaderMap, body: Bytes) -> StatusCode {
    let raw: &[u8] = &body;
    let signature = headers
        .get("X-Webhook-Signature")
        .and_then(|value| value.to_str().ok())
        .unwrap_or_default();

    let secret = std::env::var("GOZEM_WEBHOOK_SECRET").expect("secret not set");

    let mut mac = Hmac::<Sha256>::new_from_slice(secret.as_bytes()).expect("any key length");
    mac.update(raw);

    let Ok(sent) = hex::decode(signature) else {
        return StatusCode::UNAUTHORIZED;
    };

    // verify_slice compares in constant time. Comparing the hex strings with == would
    // leak the signature one byte at a time.
    if mac.verify_slice(&sent).is_err() {
        return StatusCode::UNAUTHORIZED;
    }

    let Ok(event) = serde_json::from_slice::<Event>(raw) else {
        return StatusCode::BAD_REQUEST;
    };

    // Retries mean the same event can arrive twice. Record the guid; if it was already
    // there, this delivery is a duplicate and there is nothing to do.
    if !record_event(&event.guid) {
        return StatusCode::OK;
    }

    tokio::spawn(handle_event(event));
    StatusCode::OK
}

#[tokio::main]
async fn main() {
    let app = Router::new().route("/webhooks/gozem", post(webhook));
    let listener = tokio::net::TcpListener::bind("0.0.0.0:8080").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class WebhookController {

  private static final ObjectMapper MAPPER = new ObjectMapper();
  private static final byte[] SECRET =
      System.getenv("GOZEM_WEBHOOK_SECRET").getBytes(StandardCharsets.UTF_8);

  @PostMapping("/webhooks/gozem")
  public ResponseEntity<String> handle(
      // byte[] rather than a mapped type, so Spring hands over the bytes as sent. Let
      // it deserialize and the signature will not match what you recompute.
      @RequestBody byte[] raw,
      @RequestHeader(value = "X-Webhook-Signature", required = false) String signature)
      throws Exception {

    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(SECRET, "HmacSHA256"));

    byte[] want = mac.doFinal(raw);
    byte[] sent = hexToBytes(signature);

    // isEqual is the constant-time comparison. Arrays.equals is not.
    if (sent == null || !MessageDigest.isEqual(want, sent)) {
      return ResponseEntity.status(401).body("invalid signature");
    }

    JsonNode event;
    try {
      event = MAPPER.readTree(raw);
    } catch (Exception e) {
      return ResponseEntity.badRequest().body("malformed payload");
    }

    // Retries mean the same event can arrive twice. Record the guid; if it was already
    // there, this delivery is a duplicate and there is nothing to do.
    if (!recordEvent(event.get("guid").asText())) {
      return ResponseEntity.ok().build();
    }

    queue.submit(() -> handleEvent(event));
    return ResponseEntity.ok().build();
  }

  private static byte[] hexToBytes(String hex) {
    if (hex == null || hex.length() % 2 != 0) return null;
    byte[] out = new byte[hex.length() / 2];
    for (int i = 0; i < out.length; i++) {
      out[i] = (byte) Integer.parseInt(hex.substring(i * 2, i * 2 + 2), 16);
    }
    return out;
  }
}

require 'json'
require 'openssl'
require 'sinatra'

SECRET = ENV.fetch('GOZEM_WEBHOOK_SECRET')

post '/webhooks/gozem' do
  request.body.rewind
  raw = request.body.read
  signature = request.env['HTTP_X_WEBHOOK_SIGNATURE'].to_s

  want = OpenSSL::HMAC.hexdigest('SHA256', SECRET, raw)

  # secure_compare is constant time. == would leak the signature one byte at a time.
  unless OpenSSL.secure_compare(want, signature)
    halt 401, 'invalid signature'
  end

  begin
    event = JSON.parse(raw)
  rescue JSON::ParserError
    halt 400, 'malformed payload'
  end

  # Retries mean the same event can arrive twice. Record the guid; if it was already
  # there, this delivery is a duplicate and there is nothing to do.
  halt 200 unless record_event(event['guid'])

  Thread.new { handle_event(event) }
  status 200
end