go1-webhooks

Go1 Webhooks

When to Use This Skill

• How do I receive Go1 webhooks?
• How do I verify the Go1-Signature header?
• How do I handle enrollment.create, enrollment.update, or enrollment.delete events?
• Why is my Go1 webhook signature verification failing?
• Why does the Go1 timestamp look like it is in the wrong unit?

Essential Code (USE THIS)

Go1 signs a webhook only when a secret_key (max 64 characters) is set on it. Every signed request carries:

Go1-Signature: t=<unix MILLISECONDS>,v1=<hex>

v1 is the hex HMAC-SHA256 of "<t>.<raw JSON body>", keyed with secret_key as a UTF-8 string. Use t exactly as received (do not convert it to seconds). This is not Standard Webhooks.

Verification (Node.js)

const crypto = require('crypto');

// rawBody: Buffer of the exact request bytes (express.raw, not express.json)
// toleranceSeconds = 0 (default) skips the timestamp window; a positive value opts in
function verifyGo1Webhook(rawBody, header, secret, toleranceSeconds = 0) {
  if (!header || !secret) return false;
  const parts = header.split(',').map((p) => p.trim().split('='));
  const t = parts.find(([k]) => k === 't')?.[1];
  const sigs = parts.filter(([k]) => k === 'v1').map(([, v]) => v);
  if (!t || !/^\d+$/.test(t) || sigs.length === 0) return false;
  // t is in milliseconds
  if (toleranceSeconds > 0 && Math.abs(Date.now() - Number(t)) > toleranceSeconds * 1000) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest('hex');
  return sigs.some((sig) => {
    try { return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)); }
    catch { return false; }
  });
}

Verification (Python)

import hashlib, hmac, time

def verify_go1_webhook(raw_body: bytes, header: str | None, secret: str, tolerance: int = 0) -> bool:
    if not header or not secret:
        return False
    pairs = [p.strip().split("=", 1) for p in header.split(",") if "=" in p]
    t = next((v for k, v in pairs if k == "t"), None)
    sigs = [v for k, v in pairs if k == "v1"]
    if not t or not (t.isascii() and t.isdigit()) or not sigs:
        return False
    if tolerance > 0 and abs(time.time() * 1000 - int(t)) > tolerance * 1000:  # t is milliseconds
        return False
    expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(s, expected) for s in sigs)