Skip to documentation
On this page
GearDex DocsPlatform API

Webhooks

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

Studio APIv1Updated August 2026
Twilight reflected across the Salton Sea with distant shoreline lights
GearDex LogoGearDex
3 endpoints listening

Event delivery

Webhook activity

shoot.updated200

74 ms

gear.created200

91 ms

maintenance.updated503

5.0 s · retry in 15m

PayloadSignature valid
{
 "id": "evt_91J4",
 "type": "shoot.updated",
 "data": {
 "status": "confirmed"
 }
}

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.

Events

GearDex Studio webhook templates
NameTypeDescription
Automation IntakeZapier / MakeSend new and changed shoot work into no-code automation flows. Recommended events: shoot.created, shoot.updated, gear.updated.
CRM HandoffClient OpsNotify a CRM or client workspace when shoots move forward. Recommended events: shoot.created, shoot.updated, shoot.deleted.
Inventory SyncAsset SystemsMirror gear additions, edits, and removals into external asset tools. Recommended events: gear.created, gear.updated, gear.deleted.
Maintenance AlertsOps QueuePush service records into shop queues, Slack-style alerts, or work orders. Recommended events: maintenance.created, maintenance.updated, maintenance.deleted.
Security AuditAccess ReviewTrack Studio API key creation and revocation in an external audit log. Recommended events: api_key.created, api_key.revoked.

Headers

GearDex webhook request headers
NameTypeDescription
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.

Verify 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

Next.js route handler

import { NextResponse } from "next/server"
import { verifyGearDexWebhook } from "@/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.