# 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)

```javascript
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)

```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)

```

Reject the request with `400` when verification fails. The timestamp check is **off by default**: retries and replays (including Hookdeck's) keep the original `t`, so a freshness window would reject late redeliveries. Set `GO1_TIMESTAMP_TOLERANCE_SECONDS` to a positive number of seconds to opt in.

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/go1-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/go1-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/go1-webhooks/examples/fastapi/).

## Common Event Types

The event name is in the `event_type` field of the JSON body.

| Event | Description |
| --- | --- |
| `enrollment.create` | A learner was enrolled in a learning object |
| `enrollment.update` | An enrollment changed (e.g. progress or status) |
| `enrollment.delete` | An enrollment was removed |

> **For the full event reference**, see [Go1 webhooks](https://developers.go1.com/docs/developer-tools/webhooks/overview-webhooks/). More detail in [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/go1-webhooks/references/overview.md).

## Important Headers

| Header | Description |
| --- | --- |
| `Go1-Signature` | `t=<unix milliseconds>,v1=<hex HMAC-SHA256>`; only present when `secret_key` is set |

## Environment Variables

```bash
GO1_WEBHOOK_SECRET=your_secret_key   # the secret_key you set on the webhook (max 64 chars)
GO1_TIMESTAMP_TOLERANCE_SECONDS=0    # optional; a positive value opts in to the freshness window

```

## Local Development

```bash
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 go1 --path /webhooks/go1

```

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/go1-webhooks/references/overview.md) - Go1 webhook concepts and events
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/go1-webhooks/references/setup.md) - Creating a webhook and setting `secret_key`
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/go1-webhooks/references/verification.md) - Signature verification details and gotchas