# SnapCount Signed Outbound Webhooks

SnapCount posts a signed JSON event to your HTTPS endpoint every time a counter moves. Available to Pro and Enterprise organizations. Owners and admins manage endpoints in Settings, Developers; an organization can hold up to 10 endpoints. Endpoints must use HTTPS and cannot point at a private address.

## Event types

- `counter.increment`: a counter went up.
- `counter.decrement`: a counter went down.
- `threshold.alert.fired`: an Enterprise capacity threshold alert fired. Pro can subscribe, but the event is only produced by an Enterprise alert.

## Payloads

Every event has the same envelope: `id`, `type`, `createdAt`, and `data`. The `id` is built from the event itself, so one count always has the same id, even across retries. `counter.decrement` has the same shape as an increment with a negative `delta`.

```json
{
  "id": "counter.increment:cm1gatea0001:5812",
  "type": "counter.increment",
  "createdAt": "2026-09-26T18:42:10.000Z",
  "data": {
    "organizationId": "cm1org0001",
    "counterId": "cm1gatea0001",
    "counterName": "Gate A",
    "previousCount": 186,
    "count": 187,
    "delta": 1,
    "lastEventId": 5812
  }
}
```

```json
{
  "id": "threshold.alert.fired:cm1evt5901",
  "type": "threshold.alert.fired",
  "createdAt": "2026-09-26T19:05:00.000Z",
  "data": {
    "organizationId": "cm1org0001",
    "alertId": "cm1alert0007",
    "eventId": "cm1evt5901",
    "scope": "group",
    "kind": "percent",
    "counterId": null,
    "groupId": "cm1group0002",
    "observedValue": 912,
    "thresholdValue": 900,
    "referenceValue": 1000,
    "targetName": "Main hall"
  }
}
```

## Headers

```http
POST /snapcount HTTP/1.1
Content-Type: application/json
User-Agent: SnapCount-Webhooks/1.0
X-SnapCount-Signature: t=1790448130,v1=5f8c...
X-SnapCount-Timestamp: 1790448130
X-SnapCount-Event: counter.increment
X-SnapCount-Delivery: cm1dlv0042
```

- `X-SnapCount-Signature`: `t=<unix seconds>,v1=<hex>`, an HMAC-SHA256 of `${timestamp}.${rawBody}` keyed with the endpoint secret (`whsec_...`, shown once when you create the endpoint).
- `X-SnapCount-Timestamp`: the same unix timestamp in seconds.
- `X-SnapCount-Event`: the event type.
- `X-SnapCount-Delivery`: a delivery id that stays the same across retries. Use it to ignore duplicates.

## Verify the signature

Verify against the raw body before parsing JSON, and compare in constant time.

```javascript
import { createHmac, timingSafeEqual } from "node:crypto"

// secret: your endpoint's whsec_... value.
// rawBody: the body as received, before JSON parsing.
export function verifySnapCount(rawBody, header, secret) {
  const parts = Object.fromEntries(
    header.split(",").map((part) => part.trim().split("=")),
  )
  const expected = createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex")
  const received = Buffer.from(parts.v1 ?? "")
  const wanted = Buffer.from(expected)
  return received.length === wanted.length && timingSafeEqual(received, wanted)
}
```

```python
import hashlib
import hmac

# secret: your endpoint's whsec_... value.
# raw_body: the body bytes as received, before JSON parsing.
def verify_snapcount(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(part.strip().split("=", 1) for part in header.split(","))
    signed = f"{parts['t']}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts.get("v1", ""), expected)
```

## Retries and responses

Reply with any 2xx within 10 seconds to acknowledge a delivery. Any other status, or no answer, is retried after 30 seconds, 2 minutes, 10 minutes, 1 hour, and 6 hours. A 410 response stops retries for that delivery.
