GunSpec

My Webhooks

Register HTTPS endpoints to be told when GunSpec data changes, instead of polling for it. Subscribe to events such as firearm.created or firearm.updated and the changed record is delivered to your server in the same shape the API returns it, so a local mirror can be kept current without a second call. Requires Studio tier or higher.

Auth RequiredExplorer+

Test Webhook Endpoint

Sends a signed test event to the endpoint so you can verify your receiver and signature check before relying on real events.

POST/v1/me/webhooks/{endpointId}/test

Explorer+

  • stringheaderrequired

    Your API key. Authorization: Bearer <key> is accepted in its place.

  • stringrequired

    Webhook endpoint id

    Example

application/json

  • object

    The response payload.

  • boolean

    Whether your endpoint answered with a 2xx.

  • integer | null

    The status your endpoint returned. Null when the request never got a response: DNS failure, timeout, TLS error.

  • string | null

    Why the calculation could not be completed, or null when it succeeded.

  • 400VALIDATION_ERRORValidation error
  • 401UNAUTHORIZEDAPI key required
  • 403FORBIDDENValid key, not permitted
  • 404NOT_FOUNDResource not found
  • 429RATE_LIMITEDRate limit exceeded
  • 500INTERNAL_ERRORUnexpected server error

Requires Studio tier or higher.

The test payload is a synthetic test.ping event and will not affect your application data.

A delivered: false result with status 422 means your server responded but with a non-2xx code.

Connection timeouts after 10 seconds are reported as delivery failures.

Payload envelope: every delivery (test or real) is a JSON body shaped { "id": "evt_...", "type": "firearm.updated", "created_at": "<ISO 8601>", "data": { ... } }. data is the affected record. The request also carries Content-Type: application/json and User-Agent: GunSpec-Webhooks/1.0.

Verifying deliveries: each request includes an X-Webhook-Signature: t=<unix_timestamp>,v1=<hex> header. Recompute v1 as the lowercase hex HMAC-SHA256 of the string t.rawRequestBody (the timestamp, a literal dot, then the raw body) keyed with your endpoint secret, then compare in constant time. Reject the delivery if it does not match, or if t is more than ~5 minutes old (replay protection).

Always hash the raw request body before any JSON parsing or re-serialisation, otherwise the signature will not match.

Delivery and retries: a 2xx response marks the delivery successful. Non-2xx responses and timeouts are retried up to 3 times with a 1m, 5m, 15m backoff, after which the delivery is marked failed.

Full rate limits

Minimum tier
Explorer+
Monthly quota
200/mo
Rate limit
10/min
Daily cap
50

Figures shown are for this endpoint's minimum tier. Higher tiers raise every limit.