Skip to content
New

Client galleries are here.

See Galleries

Webhooks

Keep external systems synchronized with signed events emitted by Studio API writes and matching changes inside GearDex.

StudioThe Studio API, webhooks, and MCP adapter are included with the Studio plan.Compare plans

Download Markdown

Event delivery

GearDex sends an HTTP POST request to each subscribed endpoint. The body is JSON and the signature covers the exact raw body bytes received by your server.

Webhook delivery behavior
RuleValueDetail
MethodPOSTJSON body, User-Agent GearDex-Webhooks/1.0.
Timeout5 secondsA delivery that does not respond in time counts as failed.
Success2xxAny other status is recorded as a failed attempt.
AttemptsUp to 5Retries after 15 minutes, 1 hour, 6 hours, then 24 hours.
Endpoint URLHTTPSPrivate, local, and credential-bearing URLs are rejected.

Events

Subscribe each endpoint to the events it needs. Studio API writes and matching changes inside GearDex both emit events.

Gear
gear.createdgear.updatedgear.deleted
Shoots
shoot.createdshoot.updatedshoot.deleted
Maintenance
maintenance.createdmaintenance.updatedmaintenance.deleted
Lending
loan.checked_outloan.returnedloan.due_soonloan.overdueflag.raised
API keys
api_key.createdapi_key.revoked
Testing
webhook.test
Business
booking.requestedbooking.confirmedbooking.cancelledquote.acceptedcontract.signedinvoice.paiddeliverable.delivered

Payload

Every delivery wraps the changed record in the same envelope. data carries the record fields, for example gear_type and id on gear events.

jsonEvent body
{
  "id": "event_uuid",
  "type": "gear.updated",
  "created_at": "2026-08-02T19:48:22.000Z",
  "data": { }
}

Headers

GearDex webhook request headers
HeaderFormatDescription
X-GearDex-Event-IdUUIDStable identifier for idempotency and replay protection.
X-GearDex-Event-TypestringEvent name such as gear.updated, shoot.created, or webhook.test.
X-GearDex-Webhook-IdUUIDThe configured Studio webhook endpoint that received the event.
X-GearDex-TimestampUnix timeTimestamp included in the signed payload string.
X-GearDex-SignatureHMAC-SHA256Signature formatted as t=<timestamp>,v1=<hex digest>.

Verify signatures

Compute the expected digest from <timestamp>.<rawBody> and the endpoint's signing secret. Compare signatures with a constant-time function.

jsVerify signature (Node.js)
import crypto from "node:crypto"

export function verifyGearDexWebhook({ rawBody, signatureHeader, signingSecret }) {
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((part) => part.split("="))
  )
  const timestamp = parts.t
  const signature = parts.v1
  if (!timestamp || !signature) return false

  const expected = crypto
    .createHmac("sha256", signingSecret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex")

  if (signature.length !== expected.length) return false

  return crypto.timingSafeEqual(
    Buffer.from(signature, "hex"),
    Buffer.from(expected, "hex")
  )
}

Receive an event

tsNext.js route handler
import { NextResponse } from "next/server"
import { verifyGearDexWebhook } from "@/site/lib/geardex-webhooks"

export async function POST(request) {
  const rawBody = await request.text()
  const verified = verifyGearDexWebhook({
    rawBody,
    signatureHeader: request.headers.get("x-geardex-signature") || "",
    signingSecret: process.env.GEARDEX_WEBHOOK_SECRET,
  })

  if (!verified) {
    return NextResponse.json({ error: "Invalid signature" }, { status: 401 })
  }

  const event = JSON.parse(rawBody)
  // Enqueue work using event.id as the idempotency key.
  return NextResponse.json({ received: event.id })
}

Retries and replay

GearDex retries failed deliveries on a backoff schedule. Studio owners can inspect and replay recent deliveries from Settings, so consumers should treat the event ID as an idempotency key.

  • Return a 2xx response only after the event is safely accepted.
  • Expect the same event ID to arrive more than once.
  • Keep signing secrets outside source control.
  • Rotate an endpoint secret after suspected exposure.

Endpoint templates

GearDex offers starting templates when you add an endpoint in Settings. Each one preselects the recommended events.

Automation Intake

Zapier / Make

Send new and changed shoot work into no-code automation flows.

shoot.createdshoot.updatedgear.updated

CRM Handoff

Client Ops

Notify a CRM or client workspace when shoots move forward.

shoot.createdshoot.updatedshoot.deleted

Inventory Sync

Asset Systems

Mirror gear additions, edits, and removals into external asset tools.

gear.createdgear.updatedgear.deleted

Maintenance Alerts

Ops Queue

Push service records into shop queues, Slack-style alerts, or work orders.

maintenance.createdmaintenance.updatedmaintenance.deleted

Lending Alerts

Slack / Ops

Post check-outs, returns, overdue gear, and flagged issues to a team channel.

loan.checked_outloan.returnedloan.due_soonloan.overdueflag.raised

Security Audit

Access Review

Track Studio API key creation and revocation in an external audit log.

api_key.createdapi_key.revoked

Search documentation

Start here