Webhooks

client.webhooks verifies the HMAC signature on an inbound webhook and returns a typed WebhookEvent. See Webhooks for the conceptual model and signing algorithm. No network call is made — verification is local crypto against the whsec_... secret you saved in the developer portal. Works on Node 18+, browsers, Deno, Bun, and Cloudflare Workers via WebCrypto.

Verifying a delivery

import { Spine, SpineWebhookSignatureError } from 'spine-sdk';

const client = new Spine({ apiKey: process.env.SPINE_API_KEY! });

export async function handleSpineWebhook(
  rawBody: Uint8Array | string,
  sigHeader: string,
) {
  try {
    const event = await client.webhooks.constructEvent(
      rawBody,
      sigHeader,
      process.env.SPINE_WEBHOOK_SECRET!,
    );
    if (event.type === 'run.completed') {
      // persist event.data.object.run_id etc.
    }
    return { ok: true };
  } catch (err) {
    if (err instanceof SpineWebhookSignatureError) {
      return { ok: false, status: 400 };
    }
    throw err;
  }
}

Pass the raw request body bytes, not the parsed JSON — frameworks may reorder keys during re-serialization and the signature will no longer verify.

Argument	Type	Default	Description
`payload`	`Uint8Array \| ArrayBuffer \| string`	required	Raw request body.
`sigHeader`	`string`	required	Value of the `Spine-Signature` request header.
`secret`	`string`	required	The `whsec_...` secret from the developer portal.
`options.toleranceSeconds`	`number`	`300`	Replay window in seconds.
`options.now`	`number`	`Math.floor(Date.now() / 1000)`	Inject for deterministic tests.

Returns a Promise<WebhookEvent>. Throws SpineWebhookSignatureError on any verification failure.

Express example

Express parses JSON by default and discards the raw bytes the signature was computed over. Use express.raw() on the webhook route so the SDK receives untouched bytes.

import express from 'express';
import { Spine, SpineWebhookSignatureError } from 'spine-sdk';

const app = express();
const client = new Spine({ apiKey: process.env.SPINE_API_KEY! });

app.post(
  '/webhooks/spine',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    try {
      const event = await client.webhooks.constructEvent(
        req.body,                                          // Buffer → Uint8Array-compatible
        req.header('Spine-Signature') ?? '',
        process.env.SPINE_WEBHOOK_SECRET!,
      );
      // Dedupe on event.id, then dispatch event.type
      res.status(200).json({ ok: true });
    } catch (err) {
      if (err instanceof SpineWebhookSignatureError) {
        return res.status(400).json({ error: 'invalid signature' });
      }
      throw err;
    }
  },
);

Next.js route handler

// app/api/webhooks/spine/route.ts
import { NextRequest } from 'next/server';
import { Spine, SpineWebhookSignatureError } from 'spine-sdk';

const client = new Spine({ apiKey: process.env.SPINE_API_KEY! });

export async function POST(req: NextRequest) {
  const raw = new Uint8Array(await req.arrayBuffer());
  try {
    const event = await client.webhooks.constructEvent(
      raw,
      req.headers.get('Spine-Signature') ?? '',
      process.env.SPINE_WEBHOOK_SECRET!,
    );
    // dispatch event.type
    return Response.json({ ok: true });
  } catch (err) {
    if (err instanceof SpineWebhookSignatureError) {
      return Response.json({ error: 'invalid signature' }, { status: 400 });
    }
    throw err;
  }
}

`WebhookEvent`

Field	Type	Notes
`id`	`string`	`evt_<uuid>`. Use for idempotency.
`type`	`string`	e.g. `"run.completed"`, `"run.failed"`, `"webhook.ping"`.
`created`	`number`	Unix seconds.
`livemode`	`boolean`	`true` in production.
`api_version`	`string \| undefined`	Envelope schema version.
`data`	`{ object: Record<string, unknown> }`	Event payload. `data.object` carries the primary entity.

Notes

Clock skew matters. If your server drifts more than 5 minutes from Spine’s clock, deliveries will be rejected as stale. Run NTP.
Rotation invalidates the previous secret immediately. Update your env var before rotating if you care about strict uptime.
The SDK accepts multiple v1= values in one header, so a future dual-signing rotation strategy will be forward-compatible.

Get Started

Concepts

Use with agents

Endpoints

Resources

Python SDK

TypeScript SDK

Runs

Canvas

Verifying a delivery

Express example

Next.js route handler

`WebhookEvent`

Notes

​Verifying a delivery

​Express example

​Next.js route handler

​WebhookEvent

​Notes

Verifying a delivery

Express example

Next.js route handler

`WebhookEvent`

Notes