Webhooks

What you can subscribe to

Every event below is accepted by the API today. This list is the same one that validates your subscription request, so it cannot offer something you would be refused. A change means the fields we serve actually moved, decided by the same comparison that sets updatedAt, so your webhook and your conditional request can never disagree.

catalog.resynced arrives when more than 1,000 records change at once, which means the catalog was re-derived rather than corrected. Re-sync from the API when you see it; do not try to apply it as a per-record change. It reaches every endpoint subscribed to any event, whether or not you asked for this one, because the alternative is silence on the one day your whole copy went stale.

Registering an endpoint

Your URL must be reachable from the public internet and answer quickly. How many endpoints you may hold depends on your plan:

• studio5 endpoint
• enterprise20 endpoint

1# The signing secret is in this response and nowhere else.2# Store it before you close the terminal.3curl -sS -X POST \4  -H "X-API-Key: $GUNSPEC_API_KEY" \5  -H 'Content-Type: application/json' \6  -d '{7        "url": "https://your-app.example.com/hooks/gunspec",8        "description": "catalog mirror",9        "events": ["firearm.created", "firearm.updated", "firearm.deleted"]10      }' \11  https://api.gunspec.io/v1/me/webhooks12 13# Send yourself a test delivery to prove the receiver before relying on it.14curl -sS -X POST \15  -H "X-API-Key: $GUNSPEC_API_KEY" \16  https://api.gunspec.io/v1/me/webhooks/wh_.../test

The signing secret is returned by the create call and never again. No endpoint will show it to you later, so if you lose it, delete the endpoint and register a new one.

What a delivery looks like

A POST carrying one event. The data is the record in the same shape the detail endpoint returns it for your plan, version included, so it can go straight into your own store without a second call. A deletion carries the id alone. It is the one change a poller cannot see, because a record it holds simply stops appearing, which is indistinguishable from a filter it got wrong.

1POST /hooks/gunspec HTTP/1.12Content-Type: application/json3X-Webhook-Id: evt_2f418305-4d11-4d2f-8075-994326c312764X-Webhook-Event: firearm.updated5X-Webhook-Delivery: b4c2bd96-f3a3-48e9-b6a4-b4c05489b6326X-Webhook-Signature: t=1789012345,v1=9f86d081884c7d65...7 8{9  "id": "evt_2f418305-4d11-4d2f-8075-994326c31276",10  "type": "firearm.updated",11  "created_at": "2026-09-10T08:34:48.000Z",12  "data": {13    "id": "glock-g48-mos",14    "name": "Glock G48 MOS",15    "parentFirearmId": "glock-g48",16    "barrelLengthMm": 106,17    "version": "8c1f3a90d24b",18    "updatedAt": "2026-09-10 08:34:48"19  }20}

X-Webhook-Id

Identifies the event. Unchanged across retries and identical for every endpoint that receives the same change, so this is the value to dedupe on.

X-Webhook-Event

The event type, so a receiver can route without parsing the body first.

X-Webhook-Delivery

This individual attempt, different on every retry. Quote it when asking us why something never arrived, but do not deduplicate on it.

X-Webhook-Signature

t=<unix seconds>,v1=<hex>. The hex is HMAC-SHA256 over the timestamp, a full stop, and the raw request body, keyed with your signing secret.

Verifying a delivery

Check the signature before you trust the body. Two things are easy to get wrong: sign the raw bytes you received rather than a re-serialised object, because JSON.stringify may reorder keys or change spacing; and compare in constant time so the comparison itself does not leak the expected value.

1import { createHmac, timingSafeEqual } from 'node:crypto'2 3// Verify against the RAW body. A re-serialised object will not match:4// JSON.stringify is free to reorder keys and change spacing.5export function verify(rawBody: string, header: string, secret: string): boolean {6  const parts = new Map(header.split(',').map((p) => p.split('=') as [string, string]))7  const timestamp = parts.get('t')8  const signature = parts.get('v1')9  if (!timestamp || !signature) return false10 11  // Reject anything older than five minutes so a captured delivery12  // cannot be replayed at you later.13  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false14 15  const expected = createHmac('sha256', secret)16    .update(`${timestamp}.${rawBody}`)17    .digest('hex')18 19  const a = Buffer.from(expected, 'hex')20  const b = Buffer.from(signature, 'hex')21  return a.length === b.length && timingSafeEqual(a, b)22}

Writing the receiver

Answer 2xx as soon as the signature checks out and do the work afterwards. A slow receiver is indistinguishable from a broken one and both get retried, so a handler that imports the record before replying will be sent it again while it is still working.

1// Acknowledge first, process afterwards. A slow receiver is2// indistinguishable from a broken one, and both get retried.3app.post('/hooks/gunspec', async (req, res) => {4  const raw = await readRawBody(req)5  if (!verify(raw, req.headers['x-webhook-signature'], SECRET)) {6    return res.status(401).end()7  }8 9  const event = JSON.parse(raw)10 11  // Dedupe on the event id: a retry re-sends the same one, so this is12  // what makes handling idempotent. The delivery id differs per attempt.13  if (await seen(event.id)) return res.status(200).end()14  await remember(event.id)15 16  res.status(200).end()17  await enqueue(event)18})

A non-2xx or a timeout is retried 3 times, 1, 5 and 15 minutes after the failure, and then given up on. Because a retry carries the same X-Webhook-Id, handling it twice is safe if you dedupe on that.

Still keep the conditional refresh

A webhook is a change signal, not a delivery guarantee: an endpoint can be down for longer than the retry window, and a delivery that exhausts its retries is not sent again. Keep the If-None-Match refresh loop on the Caching page as the backstop and let webhooks decide when to run it. You then re-check on a schedule you control and pay nothing for the records that have not changed.