Agent skill

GitBook Webhooks Skill

Receive and verify GitBook webhooks. Use when configuring GitBook webhook endpoints, debugging x-gitbook-signature signatures, or handling space_content_updated, page_feedback, site_view.

Install this skill

npx skills add hookdeck/webhook-skills --skill gitbook-webhooks

Receive GitBook content updates, page feedback and site views.

When to Use This Skill

Configure a receiver for GitBook webhook deliveries.
Diagnose x-gitbook-signature verification failures.
Handle space_content_updated, page_feedback, site_view.

Setup

Install the Webhook integration in your GitBook organisation, configure its endpoint URL, and select events for the space or site. Configure the matching signing secret in your receiver. The guide does not specify where this secret is shown; confirm it in your installation or with GitBook.

Set GITBOOK_WEBHOOK_SECRET in the server environment. Read setup before enabling delivery.

Verification (core)

x-gitbook-signature contains t=<Unix seconds>,v1=<hex> over timestamp + "." + raw body. Use HMAC-SHA256 with the secret's UTF-8 bytes. Verify the original bytes before parsing JSON. Validate the digest format, then compare equal-length buffers in constant time.

After extracting the documented digest and constructing message as described in verification, the comparison is:

const expected = crypto.createHmac('sha256', secret).update(message).digest();
if (digest.length !== 64 || !/^[0-9a-fA-F]{64}$/.test(digest)) return false;
const received = Buffer.from(digest, 'hex');
return received.length === expected.length && crypto.timingSafeEqual(received, expected);

Set GITBOOK_WEBHOOK_TOLERANCE_SECONDS to a positive number to enforce an application age limit in seconds. Unset or 0 disables it. Old timestamps remain valid by default so Hookdeck retries and replays can retain the original headers.

Complete handlers and tests: Express, Next.js, FastAPI.

Event Handling

Dispatch on type: space_content_updated is a space event; page_feedback and site_view are site events. The envelope includes eventId and installationId.

Return a successful HTTP response promptly. Keep processing idempotent using eventId, and accommodate retries.

Local Development

npx hookdeck-cli listen 3000 gitbook --path /webhooks/gitbook

Use port 8000 for FastAPI. The CLI provides a local tunnel and inspection UI; no account is required to start.