# 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](https://github.com/hookdeck/webhook-skills/blob/main/skills/gitbook-webhooks/references/setup.md) 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](https://github.com/hookdeck/webhook-skills/blob/main/skills/gitbook-webhooks/references/verification.md), the comparison is:

```javascript
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](https://github.com/hookdeck/webhook-skills/tree/main/skills/gitbook-webhooks/examples/express/), [Next.js](https://github.com/hookdeck/webhook-skills/tree/main/skills/gitbook-webhooks/examples/nextjs/), [FastAPI](https://github.com/hookdeck/webhook-skills/tree/main/skills/gitbook-webhooks/examples/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

```bash
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.

## Resources

* [Overview and event routing](https://github.com/hookdeck/webhook-skills/blob/main/skills/gitbook-webhooks/references/overview.md)
* [Endpoint and secret setup](https://github.com/hookdeck/webhook-skills/blob/main/skills/gitbook-webhooks/references/setup.md)
* [Verification and troubleshooting](https://github.com/hookdeck/webhook-skills/blob/main/skills/gitbook-webhooks/references/verification.md)