Callbacks

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

const CALLBACK_SECRET = process.env.HTP_CALLBACK_SECRET;
const CALLBACK_URL = new URL(process.env.HTP_CALLBACK_URL); // as set in the console
const CALLBACK_PATH = CALLBACK_URL.pathname + CALLBACK_URL.search;

const app = express();

app.post(CALLBACK_URL.pathname, express.raw({ type: '*/*' }), async (req, res) => {
  const ts = req.get('X-Timestamp') ?? '';
  const nonce = req.get('X-Nonce') ?? '';
  const eventId = req.get('Idempotency-Key') ?? '';
  const given = Buffer.from(req.get('X-Signature') ?? '', 'base64');

  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.sendStatus(401);
  const bodyHash = crypto.createHash('sha256').update(req.body).digest('hex');
  const expected = crypto
    .createHmac('sha256', CALLBACK_SECRET)
    .update(['POST', CALLBACK_PATH, ts, nonce, eventId, bodyHash].join('\n'))
    .digest();
  if (given.length !== expected.length || !crypto.timingSafeEqual(given, expected)) return res.sendStatus(401);

  const event = JSON.parse(req.body.toString('utf8'));
  res.sendStatus(200); // acknowledge fast…
  await handleEvent(event); // …then do the work (or enqueue it)
});

import base64, hashlib, hmac, json, os, time
from urllib.parse import urlsplit
from flask import Flask, request, abort

CALLBACK_SECRET = os.environ["HTP_CALLBACK_SECRET"].encode()
u = urlsplit(os.environ["HTP_CALLBACK_URL"])  # as set in the console
CALLBACK_PATH = (u.path or "/") + (f"?{u.query}" if u.query else "")

app = Flask(__name__)

@app.post(u.path or "/")
def htp_callback():
    raw = request.get_data()  # raw bytes, before parsing
    ts = request.headers.get("X-Timestamp", "")
    nonce = request.headers.get("X-Nonce", "")
    event_id = request.headers.get("Idempotency-Key", "")
    given = request.headers.get("X-Signature", "")

    if not ts.isdigit() or abs(time.time() - int(ts)) > 300:
        abort(401)
    sts = "\n".join(["POST", CALLBACK_PATH, ts, nonce, event_id, hashlib.sha256(raw).hexdigest()])
    expected = base64.b64encode(hmac.new(CALLBACK_SECRET, sts.encode(), hashlib.sha256).digest()).decode()
    if not hmac.compare_digest(expected, given):
        abort(401)

    enqueue(json.loads(raw))  # process asynchronously
    return "", 200

func HTPCallback(secret []byte, callbackPath string, handle func(Event) error) http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		raw, err := io.ReadAll(io.LimitReader(r.Body, 1<<20))
		if err != nil {
			http.Error(w, "bad body", http.StatusBadRequest)
			return
		}
		ts := r.Header.Get("X-Timestamp")
		sec, err := strconv.ParseInt(ts, 10, 64)
		if err != nil || math.Abs(float64(time.Now().Unix()-sec)) > 300 {
			http.Error(w, "stale", http.StatusUnauthorized)
			return
		}
		sum := sha256.Sum256(raw)
		sts := strings.Join([]string{"POST", callbackPath, ts, r.Header.Get("X-Nonce"),
			r.Header.Get("Idempotency-Key"), hex.EncodeToString(sum[:])}, "\n")
		mac := hmac.New(sha256.New, secret)
		mac.Write([]byte(sts))
		given, _ := base64.StdEncoding.DecodeString(r.Header.Get("X-Signature"))
		if !hmac.Equal(given, mac.Sum(nil)) {
			http.Error(w, "bad signature", http.StatusUnauthorized)
			return
		}
		var ev Event
		if err := json.Unmarshal(raw, &ev); err != nil {
			http.Error(w, "bad json", http.StatusBadRequest)
			return
		}
		if err := handle(ev); err != nil { // idempotent, quick
			http.Error(w, "retry", http.StatusInternalServerError)
			return
		}
		w.WriteHeader(http.StatusOK)
	}
}

<?php
$raw = file_get_contents('php://input');
$ts = $_SERVER['HTTP_X_TIMESTAMP'] ?? '';
$nonce = $_SERVER['HTTP_X_NONCE'] ?? '';
$eventId = $_SERVER['HTTP_IDEMPOTENCY_KEY'] ?? '';
$given = $_SERVER['HTTP_X_SIGNATURE'] ?? '';

$u = parse_url(getenv('HTP_CALLBACK_URL')); // as set in the console
$path = ($u['path'] ?? '/') . (isset($u['query']) ? '?' . $u['query'] : '');

if (!ctype_digit($ts) || abs(time() - (int) $ts) > 300) {
    http_response_code(401);
    exit;
}
$sts = implode("\n", ['POST', $path, $ts, $nonce, $eventId, hash('sha256', $raw)]);
$expected = base64_encode(hash_hmac('sha256', $sts, getenv('HTP_CALLBACK_SECRET'), true));
if (!hash_equals($expected, $given)) {
    http_response_code(401);
    exit;
}

$event = json_decode($raw, true);
enqueue($event);
http_response_code(200);

// Spring Boot
@RestController
public class HtpCallbackController {
    private final byte[] secret = System.getenv("HTP_CALLBACK_SECRET").getBytes(StandardCharsets.UTF_8);
    private final String callbackPath; // path + query of the callback URL set in the console

    public HtpCallbackController() {
        URI u = URI.create(System.getenv("HTP_CALLBACK_URL"));
        String path = (u.getRawPath() == null || u.getRawPath().isEmpty()) ? "/" : u.getRawPath();
        this.callbackPath = u.getRawQuery() == null ? path : path + "?" + u.getRawQuery();
    }

    @PostMapping(value = "/hooks/htp", consumes = MediaType.ALL_VALUE)
    public ResponseEntity<Void> callback(
            @RequestBody byte[] raw, // raw bytes, before parsing
            @RequestHeader("X-Timestamp") String ts,
            @RequestHeader("X-Nonce") String nonce,
            @RequestHeader("Idempotency-Key") String eventId,
            @RequestHeader("X-Signature") String signature) throws Exception {
        long sec;
        try {
            sec = Long.parseLong(ts);
        } catch (NumberFormatException e) {
            return ResponseEntity.status(401).build();
        }
        if (Math.abs(Instant.now().getEpochSecond() - sec) > 300) return ResponseEntity.status(401).build();

        String bodyHash = HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(raw));
        String sts = String.join("\n", "POST", callbackPath, ts, nonce, eventId, bodyHash);
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(secret, "HmacSHA256"));
        byte[] expected = mac.doFinal(sts.getBytes(StandardCharsets.UTF_8));
        byte[] given;
        try {
            given = Base64.getDecoder().decode(signature);
        } catch (IllegalArgumentException e) {
            return ResponseEntity.status(401).build();
        }
        if (!MessageDigest.isEqual(expected, given)) return ResponseEntity.status(401).build();

        events.enqueue(new String(raw, StandardCharsets.UTF_8)); // process async, idempotent on event_id
        return ResponseEntity.ok().build();
    }
}