Signed outbound webhooks

1. 01Someone countsA tap on Gate A: 186 to 187
2. 02SnapCount signs itHMAC-SHA256 with your endpoint secret
3. 03Your endpoint answersVerify, then reply 2xx within 10 s

Owners and admins of a Pro or Enterprise organization add endpoints in Settings, Developers, and choose which events each one receives. An organization can hold up to 10 endpoints.

• Endpoints must use HTTPS and cannot point at a private address such as localhost or 10.0.0.0/8.
• Each endpoint gets its own secret, starting with whsec_. It is shown once, when you create the endpoint.

Every event has the same envelope: an id, the type, createdAt, and a data object. Count events carry the counter and the change. The id is built from the event itself, so one count always has the same id, even across retries.

{
  "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
  }
}

counter.decrement has the same shape as an increment, with a negative delta. On a threshold alert, scope is counter or group, and kind is at_capacity, percent, or absolute.

Check the signature before you trust a delivery. Compute the HMAC over the raw body exactly as it arrived, then compare in constant time.

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

Reject old deliveries

The signed timestamp lets you refuse a replayed request. Compare t with your clock and drop anything older than a few minutes, allowing for the retry schedule below if you store and process deliveries later.

Reply with any 2xx within 10 seconds to acknowledge a delivery. Any other status, or no answer in time, schedules a retry.

1. First tryon the count
2. Retry 1+30 s
3. Retry 2+2 min
4. Retry 3+10 min
5. Retry 4+1 h
6. Retry 5+6 h