Account

Register a webhook endpoint

Registers an HTTPS endpoint to receive event deliveries. The response includes a signing secret; it is shown once and cannot be retrieved later.

Each delivery is a POST carrying X-Webhook-Signature (t=<unix>,v1=<hmac-sha256 of t.body>), X-Webhook-Id (the event, stable across retries, so dedupe on it), X-Webhook-Event and X-Webhook-Delivery (this attempt). A non-2xx response is retried three times, 1, 5 and 15 minutes apart.

Catalog events carry the record in the same shape GET /v1/firearms/{id} returns it, version included, so a cache can be updated without a second call. A deletion carries the id alone.

Requires an API key belonging to a user account. Acts on the calling account's own data.

post/v1/me/webhooks

Request

  • Base URL: https://api.gunspec.io
  • URL: https://api.gunspec.io/v1/me/webhooks
  • Auth: one of:
    • API key in header X-API-Key
    • HTTP bearer

Request body

urlstring required

Where deliveries are POSTed. A public https hostname on port 443: no IP address, no credentials in the URL, and not a gunspec.io or workers.dev host. Redirects are not followed, so register the final URL. At most 2,048 characters.

eventsstring[] required

Event types this endpoint is subscribed to. The full list is on the POST operation.

descriptionstring

Prose summary of the record, where one has been written.

Example request

{
  "url": "https://example.com/hooks/gunspec",
  "description": "Production ingest"
}

Response

The created endpoint, including its signing secret

successboolean required

Always true on a successful response. Every error carries false and an error object instead.

Example response

{
  "success": true,
  "data": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "url": "https://example.com/hooks/gunspec",
    "events": [
      "firearm.created"
    ],
    "active": true,
    "createdAt": "2026-08-23T02:00:00.000Z",
    "updatedAt": "2026-08-23T02:00:00.000Z",
    "secret": "whsec_..."
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.