Webhooks

Signed delivery of catalog changes to your own endpoint. An endpoint subscribes to events (firearm.updated, catalog.resynced and the rest) and receives the same payload GET /v1/firearms/{id} returns, so a mirror can apply a delivery without re-fetching. Every request carries a signature made with the secret create() returns once. Failed deliveries are retried on a schedule, so a brief outage at your end costs nothing.

Authentifizierung erforderlichExplorer+

client.webhooks.list()

The account's endpoints with their subscribed events and delivery health.

list(params?: ListWebhookEndpointsParams): Promise<PaginatedResponse<WebhookEndpoint>>

GET/v1/me/webhooks

Explorer+

stringHeadererforderlich
Ihr API-Schlüssel. Authorization: Bearer <key> wird ebenfalls akzeptiert.

integerstandard1
Page number, from 1 to 10,000
Bereich
1 – 10000
Beispiel
integerstandard20
Items per page (max 100)
Bereich
1 – 100
Beispiel

application/json

WebhookEndpoint[]
One page of results
string
Opaque endpoint id. Address it at /v1/me/webhooks/{endpointId}.
string
Absolute, directly fetchable URL.
string[]
Event types this endpoint is subscribed to. The full list is on the POST operation.
string | null
Prose summary of the record, where one has been written.
boolean
False while the endpoint is paused. A paused endpoint receives nothing and is not retried.
string
When the record was first added, YYYY-MM-DD HH:MM:SS in UTC.
string
When the endpoint was last changed, ISO 8601.
number
Current page number
number
Items per page
number
Total matching records (Builder and above)

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

Alle Anfragelimits

Mindeststufe: Explorer+
Monatskontingent: 200/mo
Anfragerate: 10/min
Tageslimit: 50

Die Werte gelten für die Mindeststufe dieses Endpunkts. Höhere Stufen erhöhen alle Limits.

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const { data } = await client.webhooks.list();6console.log(data);

1{2  "success": true,3  "data": [4    {5      "id": "wh_01H8...",6      "url": "https://example.com/hooks/gunspec",7      "events": [8        "firearm.created"9      ],10      "description": null,11      "active": true,12      "createdAt": "2026-08-23T02:00:00.000Z",13      "updatedAt": "2026-08-23T02:00:00.000Z"14    }15  ],16  "pagination": {17    "page": 1,18    "limit": 20,19    "per_page": 20,20    "total": 42,21    "totalPages": 322  }23}

Authentifizierung erforderlichExplorer+

client.webhooks.create()

The response is the only one that carries the signing secret; store it.

create(params: CreateWebhookEndpointParams): Promise<APIResponse<WebhookEndpointCreated>>

POST/v1/me/webhooks

Explorer+

stringHeadererforderlich
Ihr API-Schlüssel. Authorization: Bearer <key> wird ebenfalls akzeptiert.

application/json

stringerforderlich
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.
string[]erforderlich
Event types this endpoint is subscribed to. The full list is on the POST operation.
string
Prose summary of the record, where one has been written.

application/json

WebhookEndpointCreated
The response payload
string
Opaque endpoint id. Address it at /v1/me/webhooks/{endpointId}.
string
Absolute, directly fetchable URL.
string[]
Event types this endpoint is subscribed to. The full list is on the POST operation.
string | null
Prose summary of the record, where one has been written.
boolean
False while the endpoint is paused. A paused endpoint receives nothing and is not retried.
string
When the record was first added, YYYY-MM-DD HH:MM:SS in UTC.
string
When the endpoint was last changed, ISO 8601.
string
HMAC signing secret. Returned only here, on creation. No other endpoint will show it again.

400VALIDATION_ERRORValidation error
401UNAUTHORIZEDAPI key required
403FORBIDDENValid key, not permitted
413PAYLOAD_TOO_LARGERequest body too large
429RATE_LIMITEDRate limit exceeded
500INTERNAL_ERRORUnexpected server error

Alle Anfragelimits

Mindeststufe: Explorer+
Monatskontingent: 200/mo
Anfragerate: 10/min
Tageslimit: 50

Die Werte gelten für die Mindeststufe dieses Endpunkts. Höhere Stufen erhöhen alle Limits.

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const { data } = await client.webhooks.create({6  url: 'https://example.com/hooks/gunspec',7  events: ['firearm.created'],8});9console.log(data);

1{2  "success": true,3  "data": {4    "id": "wh_01H8...",5    "url": "https://example.com/hooks/gunspec",6    "events": [7      "firearm.created"8    ],9    "description": null,10    "active": true,11    "createdAt": "2026-08-23T02:00:00.000Z",12    "updatedAt": "2026-08-23T02:00:00.000Z",13    "secret": "whsec_..."14  }15}

Authentifizierung erforderlichExplorer+

client.webhooks.get()

One endpoint, with its recent delivery state.

get(id: string): Promise<APIResponse<WebhookEndpoint>>

GET/v1/me/webhooks/{endpointId}

Explorer+

stringHeadererforderlich
Ihr API-Schlüssel. Authorization: Bearer <key> wird ebenfalls akzeptiert.

stringerforderlich
Webhook endpoint id
Beispiel

application/json

WebhookEndpoint
The response payload
string
Opaque endpoint id. Address it at /v1/me/webhooks/{endpointId}.
string
Absolute, directly fetchable URL.
string[]
Event types this endpoint is subscribed to. The full list is on the POST operation.
string | null
Prose summary of the record, where one has been written.
boolean
False while the endpoint is paused. A paused endpoint receives nothing and is not retried.
string
When the record was first added, YYYY-MM-DD HH:MM:SS in UTC.
string
When the endpoint was last changed, ISO 8601.

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

Alle Anfragelimits

Mindeststufe: Explorer+
Monatskontingent: 200/mo
Anfragerate: 10/min
Tageslimit: 50

Die Werte gelten für die Mindeststufe dieses Endpunkts. Höhere Stufen erhöhen alle Limits.

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const { data } = await client.webhooks.get('wh_01H8...');6console.log(data);

1{2  "success": true,3  "data": {4    "id": "wh_01H8...",5    "url": "https://example.com/hooks/gunspec",6    "events": [7      "firearm.created"8    ],9    "description": null,10    "active": true,11    "createdAt": "2026-08-23T02:00:00.000Z",12    "updatedAt": "2026-08-23T02:00:00.000Z"13  }14}

Authentifizierung erforderlichExplorer+

client.webhooks.update()

Change an endpoint's URL, event list or enabled flag.

update(id: string, params: UpdateWebhookEndpointParams): Promise<APIResponse<WebhookEndpoint>>

PUT/v1/me/webhooks/{endpointId}

Explorer+

stringHeadererforderlich
Ihr API-Schlüssel. Authorization: Bearer <key> wird ebenfalls akzeptiert.

stringerforderlich
Webhook endpoint id
Beispiel

application/json

string
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.
string[]
Event types this endpoint is subscribed to. The full list is on the POST operation.
string
Prose summary of the record, where one has been written.
boolean
False while the endpoint is paused. A paused endpoint receives nothing and is not retried.

application/json

WebhookEndpoint
The response payload
string
Opaque endpoint id. Address it at /v1/me/webhooks/{endpointId}.
string
Absolute, directly fetchable URL.
string[]
Event types this endpoint is subscribed to. The full list is on the POST operation.
string | null
Prose summary of the record, where one has been written.
boolean
False while the endpoint is paused. A paused endpoint receives nothing and is not retried.
string
When the record was first added, YYYY-MM-DD HH:MM:SS in UTC.
string
When the endpoint was last changed, ISO 8601.

400VALIDATION_ERRORValidation error
401UNAUTHORIZEDAPI key required
403FORBIDDENValid key, not permitted
404NOT_FOUNDResource not found
413PAYLOAD_TOO_LARGERequest body too large
429RATE_LIMITEDRate limit exceeded
500INTERNAL_ERRORUnexpected server error

Alle Anfragelimits

Mindeststufe: Explorer+
Monatskontingent: 200/mo
Anfragerate: 10/min
Tageslimit: 50

Die Werte gelten für die Mindeststufe dieses Endpunkts. Höhere Stufen erhöhen alle Limits.

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const { data } = await client.webhooks.update('wh_01H8...', {6  url: 'https://example.com/hooks/gunspec',7  events: ['firearm.created'],8  description: 'Production ingest',9  active: true,10});11console.log(data);

1{2  "success": true,3  "data": {4    "id": "wh_01H8...",5    "url": "https://example.com/hooks/gunspec",6    "events": [7      "firearm.created"8    ],9    "description": null,10    "active": true,11    "createdAt": "2026-08-23T02:00:00.000Z",12    "updatedAt": "2026-08-23T02:00:00.000Z"13  }14}

Authentifizierung erforderlichExplorer+

client.webhooks.delete()

Delete an endpoint. Undelivered retries for it are dropped with it.

delete(id: string): Promise<APIResponse<{ deleted: boolean }>>

DELETE/v1/me/webhooks/{endpointId}

Explorer+

stringHeadererforderlich
Ihr API-Schlüssel. Authorization: Bearer <key> wird ebenfalls akzeptiert.

stringerforderlich
Webhook endpoint id
Beispiel

application/json

object
The response payload.
boolean
Always true: the endpoint is gone once this returns.
string
Id of the deleted endpoint.

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

Alle Anfragelimits

Mindeststufe: Explorer+
Monatskontingent: 200/mo
Anfragerate: 10/min
Tageslimit: 50

Die Werte gelten für die Mindeststufe dieses Endpunkts. Höhere Stufen erhöhen alle Limits.

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const { data } = await client.webhooks.delete('wh_01H8...');6console.log(data);

1{2  "success": true,3  "data": {4    "deleted": true,5    "id": "wh_01H8..."6  }7}

Authentifizierung erforderlichExplorer+

client.webhooks.test()

Send a signed test delivery, so a new endpoint can be verified before an event depends on it.

test(id: string): Promise<APIResponse<WebhookTestResult>>

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

Explorer+

stringHeadererforderlich
Ihr API-Schlüssel. Authorization: Bearer <key> wird ebenfalls akzeptiert.

stringerforderlich
Webhook endpoint id
Beispiel

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

Alle Anfragelimits

Mindeststufe: Explorer+
Monatskontingent: 200/mo
Anfragerate: 10/min
Tageslimit: 50

Die Werte gelten für die Mindeststufe dieses Endpunkts. Höhere Stufen erhöhen alle Limits.

1import { GunSpec } from '@buun_group/gunspec-sdk';2 3const client = new GunSpec();4 5const { data } = await client.webhooks.test('wh_01H8...');6console.log(data);

1{2  "success": true,3  "data": {4    "delivered": true,5    "httpStatus": 200,6    "error": null7  }8}

Webhooks

AutorisierungExplorer+

Abfrageparameter

Antwort200application/json

Fehler

AnfragelimitsAlle Anfragelimits

AutorisierungExplorer+

Anfrage-Bodyapplication/json

Antwort201application/json

Fehler

AnfragelimitsAlle Anfragelimits

AutorisierungExplorer+

Pfadparameter

Antwort200application/json

Fehler

AnfragelimitsAlle Anfragelimits

AutorisierungExplorer+

Pfadparameter

Anfrage-Bodyapplication/json

Antwort200application/json

Fehler

AnfragelimitsAlle Anfragelimits

AutorisierungExplorer+

Pfadparameter

Antwort200application/json

Fehler

AnfragelimitsAlle Anfragelimits

AutorisierungExplorer+

Pfadparameter

Antwort200application/json

Fehler

AnfragelimitsAlle Anfragelimits

Explorer+

application/json

Alle Anfragelimits

Explorer+

application/json

application/json

Alle Anfragelimits

Explorer+

application/json

Alle Anfragelimits

Explorer+

application/json

application/json

Alle Anfragelimits

Explorer+

application/json

Alle Anfragelimits

Explorer+

application/json

Alle Anfragelimits