Webhooks: events and signature verification

{
  "id": "del_8c1e4f7a2b9d3e05",
  "event": "registration.allowed",
  "apiVersion": "2026-10-25",
  "createdAt": "2026-11-02T12:00:01.000Z",
  "organizationId": "org_7d1c2b3a",
  "data": {
    "requestId": "AUD-MHH3K2QZ-4F1C9B2E7D10",
    "email": "player0@example.com",
    "ip": "203.0.113.24",
    "decision": "ALLOWED",
    "verdict": "ALLOWED",
    "riskScore": 4,
    "reasons": [],
    "triggers": [],
    "timestamp": "2026-11-02T12:00:00.912Z"
  }
}

{
  "id": "del_8c1e4f7a2b9d3e05",
  "event": "registration.blocked",
  "apiVersion": "2026-10-25",
  "createdAt": "2026-11-02T12:00:01.000Z",
  "organizationId": "org_7d1c2b3a",
  "data": {
    "requestId": "AUD-MHH3K30A-91B7C2D40E55",
    "email": "player1@example.com",
    "ip": "203.0.113.24",
    "decision": "QUARANTINED",
    "verdict": "QUARANTINED",
    "riskScore": 62,
    "reasons": [
      "Plus-addressed email (player+bonus@…)."
    ],
    "triggers": [
      "PLUS_ALIASED_EMAIL"
    ],
    "timestamp": "2026-11-02T12:00:00.912Z"
  }
}

{
  "id": "del_5f2c9a1e7b3d4c60",
  "event": "signup.approved",
  "apiVersion": "2026-10-25",
  "createdAt": "2026-11-02T14:31:08.000Z",
  "organizationId": "org_7d1c2b3a",
  "data": {
    "event": "signup.approved",
    "reviewId": "rev_Hk3pQ9xZ2mV7cN4bL1kJ8hG5",
    "requestId": "AUD-MHH3K31C-0C3D5E7F9A21",
    "status": "approved",
    "decisionReason": "operator",
    "decidedAt": "2026-11-02T14:31:07.000Z",
    "recommendedAction": "allow"
  }
}

{
  "id": "del_5f2c9a1e7b3d4c60",
  "event": "signup.rejected",
  "apiVersion": "2026-10-25",
  "createdAt": "2026-11-02T14:31:08.000Z",
  "organizationId": "org_7d1c2b3a",
  "data": {
    "event": "signup.rejected",
    "reviewId": "rev_Hk3pQ9xZ2mV7cN4bL1kJ8hG5",
    "requestId": "AUD-MHH3K31C-0C3D5E7F9A21",
    "status": "rejected",
    "decisionReason": "operator",
    "decidedAt": "2026-11-02T14:31:07.000Z",
    "recommendedAction": "block"
  }
}

{
  "event": "test.ping",
  "timestamp": 1793620805,
  "organizationId": "org_7d1c2b3a",
  "data": {
    "message": "InlineShield verified test delivery probe"
  }
}

{"id":"del_5f2c9a1e7b3d4c60","event":"signup.approved","apiVersion":"2026-10-25","createdAt":"2026-11-02T12:00:05.000Z","organizationId":"org_7d1c2b3a","data":{"event":"signup.approved","reviewId":"rev_Hk3pQ9xZ2mV7cN4bL1kJ8hG5","requestId":"AUD-MHH3K2QZ-4F1C9B2E7D10","status":"approved","decisionReason":"operator","decidedAt":"2026-11-02T12:00:04.000Z","recommendedAction":"allow"}}

t=1793620805,v1=0b14a41708b9a46125d31465e106465d80990634e175f4d310bc939e1ba7fa7a

// Express. X-InlineShield-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">
const express = require('express');
const crypto = require('crypto');
const app = express();

// express.raw keeps the exact bytes InlineShield signed: do NOT use express.json() on this route.
app.post('/inlineshield/webhook', express.raw({ type: '*/*' }), (req, res) => {
  const secret = process.env.INLINESHIELD_WEBHOOK_SECRET;
  if (!secret) return res.status(500).send('webhook secret not configured'); // never verify with an empty key
  const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(req.get('X-InlineShield-Signature') || '');
  if (!m || !Buffer.isBuffer(req.body) || Math.abs(Date.now() / 1000 - Number(m[1])) > 300) {
    return res.status(400).send('bad signature'); // malformed header or older/newer than 300 s
  }
  const expected = crypto.createHmac('sha256', secret)
    .update(m[1] + '.').update(req.body).digest();
  const given = Buffer.from(m[2], 'hex');
  if (given.length !== expected.length || !crypto.timingSafeEqual(given, expected)) { // constant-time
    return res.status(400).send('bad signature');
  }

  const event = JSON.parse(req.body.toString('utf8'));
  const d = event.data;
  if (event.event === 'signup.approved') {
    // Activate the account that has reviewId d.reviewId (status "approved").
  } else if (event.event === 'signup.rejected') {
    // Delete or disable the account with reviewId d.reviewId (see d.decisionReason).
  }
  // Deliveries can repeat: make the handler idempotent (key on event.id).
  res.sendStatus(200);
});

# Flask. X-InlineShield-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">
import hashlib, hmac, json, os, re, time
from flask import abort, request
# app is your Flask application: app = Flask(__name__)

@app.post("/inlineshield/webhook")
def inlineshield_webhook():
    secret = os.environ.get("INLINESHIELD_WEBHOOK_SECRET", "")
    if not secret:
        abort(500)  # never verify with an empty key
    raw = request.get_data()  # raw bytes, before any JSON parsing
    m = re.fullmatch(r"t=(\d+),v1=([0-9a-f]{64})", request.headers.get("X-InlineShield-Signature", ""))
    if not m or abs(time.time() - int(m.group(1))) > 300:
        abort(400)  # malformed header or older/newer than 300 s
    expected = hmac.new(secret.encode(),
                        m.group(1).encode() + b"." + raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, m.group(2)):  # constant-time
        abort(400)

    event = json.loads(raw)
    d = event["data"]
    if event["event"] == "signup.approved":
        pass  # activate the account that has reviewId d["reviewId"] (status "approved")
    elif event["event"] == "signup.rejected":
        pass  # delete or disable it (see d["decisionReason"])
    # Deliveries can repeat: make the handler idempotent (key on event["id"]).
    return "", 200

<?php
// Webhook receiver. X-InlineShield-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">
$secret = getenv('INLINESHIELD_WEBHOOK_SECRET');
if (!is_string($secret) || $secret === '') { http_response_code(500); exit; } // never verify with an empty key
$raw = file_get_contents('php://input'); // verify the RAW body, before json_decode
$header = $_SERVER['HTTP_X_INLINESHIELD_SIGNATURE'] ?? '';

if (!preg_match('/^t=(\d+),v1=([0-9a-f]{64})$/D', $header, $m) || abs(time() - (int)$m[1]) > 300) {
    http_response_code(400); // malformed header or older/newer than 300 s
    exit;
}
$expected = hash_hmac('sha256', $m[1] . '.' . $raw, $secret);
if (!hash_equals($expected, $m[2])) { // constant-time compare
    http_response_code(400);
    exit;
}

$event = json_decode($raw, true);
$d = $event['data'] ?? [];
if (($event['event'] ?? '') === 'signup.approved') {
    // Activate the account that has reviewId $d['reviewId'] (status "approved").
} elseif (($event['event'] ?? '') === 'signup.rejected') {
    // Delete or disable the account with reviewId $d['reviewId'] (see $d['decisionReason']).
}
// Deliveries can repeat: make the handler idempotent (key on $event['id']).
http_response_code(200);

// Spring MVC, Java 17+. X-InlineShield-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">
@PostMapping("/inlineshield/webhook")
public ResponseEntity<Void> inlineshieldWebhook(
        @RequestBody byte[] raw, // raw bytes, before any JSON parsing
        @RequestHeader(value = "X-InlineShield-Signature", defaultValue = "") String header) throws Exception {
    java.util.regex.Matcher m = java.util.regex.Pattern.compile("t=(\\d{1,12}),v1=([0-9a-f]{64})").matcher(header);
    if (!m.matches() || Math.abs(Instant.now().getEpochSecond() - Long.parseLong(m.group(1))) > 300) {
        return ResponseEntity.badRequest().build(); // malformed header or older/newer than 300 s
    }
    String secret = System.getenv("INLINESHIELD_WEBHOOK_SECRET");
    if (secret == null || secret.isEmpty()) return ResponseEntity.status(500).build(); // never verify with an empty key
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
    mac.update((m.group(1) + ".").getBytes(StandardCharsets.UTF_8));
    byte[] expected = mac.doFinal(raw);
    if (!MessageDigest.isEqual(expected, HexFormat.of().parseHex(m.group(2)))) { // constant-time
        return ResponseEntity.badRequest().build();
    }

    JsonNode event = new ObjectMapper().readTree(raw); // Jackson, or your JSON library
    JsonNode d = event.get("data");
    if ("signup.approved".equals(event.path("event").asText())) {
        // Activate the account that has reviewId d.get("reviewId") (status "approved").
    } else if ("signup.rejected".equals(event.path("event").asText())) {
        // Delete or disable it (see d.get("decisionReason")).
    }
    // Deliveries can repeat: make the handler idempotent (key on event.get("id")).
    return ResponseEntity.ok().build();
}

// ASP.NET Core minimal API. X-InlineShield-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">
app.MapPost("/inlineshield/webhook", async (HttpRequest request) =>
{
    using var ms = new MemoryStream();
    await request.Body.CopyToAsync(ms);
    var raw = ms.ToArray(); // raw bytes, before any JSON parsing

    var m = Regex.Match(request.Headers["X-InlineShield-Signature"].ToString(), @"\At=(\d{1,12}),v1=([0-9a-f]{64})\z");
    if (!m.Success || Math.Abs(DateTimeOffset.UtcNow.ToUnixTimeSeconds() - long.Parse(m.Groups[1].Value)) > 300)
        return Results.BadRequest(); // malformed header or older/newer than 300 s

    var secret = Environment.GetEnvironmentVariable("INLINESHIELD_WEBHOOK_SECRET");
    if (string.IsNullOrEmpty(secret)) return Results.StatusCode(500); // never verify with an empty key
    var key = Encoding.UTF8.GetBytes(secret);
    var signed = Encoding.UTF8.GetBytes(m.Groups[1].Value + ".").Concat(raw).ToArray();
    var expected = HMACSHA256.HashData(key, signed);
    if (!CryptographicOperations.FixedTimeEquals(expected, Convert.FromHexString(m.Groups[2].Value))) // constant-time
        return Results.BadRequest();

    using var doc = JsonDocument.Parse(raw);
    var evt = doc.RootElement;
    var d = evt.GetProperty("data");
    switch (evt.GetProperty("event").GetString())
    {
        case "signup.approved":
            // Activate the account that has reviewId d.GetProperty("reviewId") (status "approved").
            break;
        case "signup.rejected":
            // Delete or disable it (see d.GetProperty("decisionReason")).
            break;
    }
    // Deliveries can repeat: make the handler idempotent (key on evt.GetProperty("id")).
    return Results.Ok();
});