Async and webhooks

# Send a signed test webhook to your own handler, to try it before going live.
SECRET_KEY="YOUR_SECRET_KEY"
BODY='{"event":"screenshot.completed","job_id":"job_917e1044a2a8885401dae084","batch_id":null,"status":"done"}'
TIMESTAMP=$(date +%s)

# HMAC-SHA256 of "<timestamp>.<body>" as lowercase hex. openssl prints a label first, so keep the last word.
SIGNATURE=$(printf '%s.%s' "$TIMESTAMP" "$BODY" | openssl dgst -sha256 -hmac "$SECRET_KEY" -hex | awk '{print $NF}')

curl -X POST "https://your-app.example/hooks/screenshot" \
  -H "Content-Type: application/json" \
  -H "x-timestamp: $TIMESTAMP" \
  -H "x-signature: $SIGNATURE" \
  -d "$BODY"

import { createServer } from 'node:http'
import { createHmac, timingSafeEqual } from 'node:crypto'

const SECRET_KEY = process.env.SCREENSHOT_SECRET_KEY
const TOLERANCE_SECONDS = 300

function isValid(rawBody, signature, timestamp) {
  // Refuse a message that is not from about now: it may be a replay.
  if (!/^\d+$/.test(String(timestamp || ''))) return false
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > TOLERANCE_SECONDS) return false

  const expected = createHmac('sha256', SECRET_KEY).update(`${timestamp}.`).update(rawBody).digest('hex')
  const a = Buffer.from(expected)
  const b = Buffer.from(String(signature || ''))
  // timingSafeEqual throws when the lengths differ, so check that first.
  return a.length === b.length && timingSafeEqual(a, b)
}

createServer((req, res) => {
  const chunks = []
  req.on('data', (chunk) => chunks.push(chunk))
  req.on('end', () => {
    const rawBody = Buffer.concat(chunks) // the exact bytes, not parsed

    if (!isValid(rawBody, req.headers['x-signature'], req.headers['x-timestamp'])) {
      res.writeHead(401).end()
      return
    }

    const payload = JSON.parse(rawBody.toString('utf8'))
    res.writeHead(200).end() // answer first, do slow work afterwards

    console.log(payload.event, payload.job_id, payload.screenshot?.url)
  })
}).listen(3000)

import hashlib
import hmac
import json
import os
import time
from http.server import BaseHTTPRequestHandler, HTTPServer

SECRET_KEY = os.environ["SCREENSHOT_SECRET_KEY"].encode()
TOLERANCE_SECONDS = 300


def is_valid(raw_body: bytes, signature: str, timestamp: str) -> bool:
    # Refuse a message that is not from about now: it may be a replay.
    if not timestamp.isdigit() or abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS:
        return False
    signed = timestamp.encode() + b"." + raw_body
    expected = hmac.new(SECRET_KEY, signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature or "")


class Handler(BaseHTTPRequestHandler):
    def do_POST(self):
        length = int(self.headers.get("Content-Length", 0))
        raw_body = self.rfile.read(length)  # the exact bytes, not parsed

        if not is_valid(raw_body, self.headers.get("x-signature", ""), self.headers.get("x-timestamp", "")):
            self.send_response(401)
            self.end_headers()
            return

        payload = json.loads(raw_body)
        self.send_response(200)  # answer first, do slow work afterwards
        self.end_headers()

        screenshot = payload.get("screenshot") or {}
        print(payload["event"], payload["job_id"], screenshot.get("url"))


HTTPServer(("", 3000), Handler).serve_forever()

<?php
$secretKey = getenv('SCREENSHOT_SECRET_KEY');
$toleranceSeconds = 300;

// The exact bytes of the body, not parsed.
$rawBody = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
$timestamp = $_SERVER['HTTP_X_TIMESTAMP'] ?? '';

// Refuse a message that is not from about now: it may be a replay.
if (!ctype_digit($timestamp) || abs(time() - (int) $timestamp) > $toleranceSeconds) {
    http_response_code(401);
    exit;
}

$expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secretKey);

// hash_equals is a constant-time compare.
if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit;
}

$payload = json_decode($rawBody, true);
http_response_code(200);

error_log($payload['event'] . ' ' . $payload['job_id'] . ' ' . ($payload['screenshot']['url'] ?? ''));

package main

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

var secretKey = []byte(os.Getenv("SCREENSHOT_SECRET_KEY"))

const toleranceSeconds = 300

func isValid(rawBody []byte, signature, timestamp string) bool {
	// Refuse a message that is not from about now: it may be a replay.
	sentAt, err := strconv.ParseInt(timestamp, 10, 64)
	if err != nil {
		return false
	}
	age := time.Now().Unix() - sentAt
	if age > toleranceSeconds || age < -toleranceSeconds {
		return false
	}

	mac := hmac.New(sha256.New, secretKey)
	mac.Write([]byte(timestamp + "."))
	mac.Write(rawBody)
	expected := hex.EncodeToString(mac.Sum(nil))
	// hmac.Equal is a constant-time compare.
	return hmac.Equal([]byte(expected), []byte(signature))
}

func handler(w http.ResponseWriter, r *http.Request) {
	rawBody, err := io.ReadAll(r.Body) // the exact bytes, not parsed
	if err != nil || !isValid(rawBody, r.Header.Get("x-signature"), r.Header.Get("x-timestamp")) {
		w.WriteHeader(http.StatusUnauthorized)
		return
	}

	var payload struct {
		Event string `json:"event"`
		JobID string `json:"job_id"`
	}
	if err := json.Unmarshal(rawBody, &payload); err != nil {
		w.WriteHeader(http.StatusBadRequest)
		return
	}
	w.WriteHeader(http.StatusOK) // answer first, do slow work afterwards

	log.Println(payload.Event, payload.JobID)
}

func main() {
	http.HandleFunc("/hooks/screenshot", handler)
	log.Fatal(http.ListenAndServe(":3000", nil))
}

require "json"
require "openssl"
require "webrick" # on Ruby 3 and newer: gem install webrick

SECRET_KEY = ENV.fetch("SCREENSHOT_SECRET_KEY")
TOLERANCE_SECONDS = 300

# Constant-time compare that works on every Ruby version.
def secure_compare(a, b)
  return false unless a.bytesize == b.bytesize

  difference = 0
  a.bytes.zip(b.bytes) { |x, y| difference |= x ^ y }
  difference.zero?
end

def valid?(raw_body, signature, timestamp)
  # Refuse a message that is not from about now: it may be a replay.
  return false unless timestamp.to_s.match?(/\A\d+\z/)
  return false if (Time.now.to_i - timestamp.to_i).abs > TOLERANCE_SECONDS

  expected = OpenSSL::HMAC.hexdigest("SHA256", SECRET_KEY, "#{timestamp}.#{raw_body}")
  secure_compare(expected, signature.to_s)
end

server = WEBrick::HTTPServer.new(Port: 3000)

server.mount_proc "/hooks/screenshot" do |req, res|
  raw_body = req.body.to_s # the exact bytes, not parsed

  unless valid?(raw_body, req["x-signature"], req["x-timestamp"])
    res.status = 401
    next
  end

  payload = JSON.parse(raw_body)
  res.status = 200 # answer first, do slow work afterwards

  puts [payload["event"], payload["job_id"], payload.dig("screenshot", "url")].join(" ")
end

server.start