# Granola Webhooks

Granola is an AI meeting-notes app. Its webhooks tell you when a note is generated, edited or shared with you. Payloads are small notifications with no note content; you fetch the note through the Granola API afterwards. Available on Business and Enterprise plans.

## When to Use This Skill

* How do I receive Granola webhooks?
* How do I verify Granola webhook signatures (`webhook-signature`)?
* How do I handle `note.generated`, `note.edited` or `note.access_granted` events?
* Where do I get the Granola webhook signing secret?
* Why is my Granola webhook signature verification failing?

## Verification (core)

Granola signs natively per Standard Webhooks (not via Svix). Each request has `webhook-id` (equals the payload's `event_id`), `webhook-timestamp` (Unix seconds) and `webhook-signature` (space-delimited `v1,<base64>` entries). The signature is base64 HMAC-SHA256 over `{webhook-id}.{webhook-timestamp}.{raw body}`, keyed with the **base64-decoded** part of the `whsec_...` secret.

Use the `standardwebhooks` library (Node and Python). It throws on a bad signature or a timestamp more than 5 minutes off, and returns the parsed payload:

```javascript
const { Webhook } = require('standardwebhooks');   // Python: from standardwebhooks.webhooks import Webhook
const event = new Webhook(process.env.GRANOLA_WEBHOOK_SECRET).verify(rawBody, {
  'webhook-id': req.headers['webhook-id'],
  'webhook-timestamp': req.headers['webhook-timestamp'],
  'webhook-signature': req.headers['webhook-signature'],
});

```

Manual equivalent, if you can't use the library:

```javascript
const key = Buffer.from(secret.slice('whsec_'.length), 'base64');
const expected = crypto.createHmac('sha256', key)
  .update(`${id}.${timestamp}.${rawBody}`, 'utf8').digest('base64');
const ok = signatureHeader.split(' ').some((entry) => {
  const [version, sig = ''] = entry.split(',');
  const a = Buffer.from(sig), b = Buffer.from(expected);
  return version === 'v1' && a.length === b.length && crypto.timingSafeEqual(a, b);
});

```

Verify against the **raw body** before parsing JSON (in Express use `express.raw({ type: '*/*' })`), and reject old timestamps to stop replays. Hookdeck retries and replays resend the original `webhook-timestamp`, so the library rejects them once they are more than 5 minutes old. If you receive through Hookdeck and need late retries to pass, use the manual check in [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/granola-webhooks/references/verification.md) and drop or widen its timestamp window.

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/granola-webhooks/examples/express/), [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/granola-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/granola-webhooks/examples/fastapi/).

## Common Event Types

| Event (`event_type`) | Sent when |
| --- | --- |
| `note.generated` | The first AI summary for a note is generated while your endpoint can access it |
| `note.edited` | The note's summary is edited or regenerated (`data.changed_fields` is `["summary"]`) |
| `note.access_granted` | A note is shared with you, directly or via a folder |

Payload: `{ "event_id", "event_type", "note_id", "occurred_at" }`. Fetch the note with Granola's Get Note API. Subscribe to both `note.generated` and `note.access_granted` to discover notes.

## Important Headers

| Header | Description |
| --- | --- |
| `webhook-id` | Event ID; unchanged on retries, use it for idempotency |
| `webhook-timestamp` | Unix seconds of this delivery attempt |
| `webhook-signature` | `v1,<base64>` entries, space-delimited (several during rotation) |

## Environment Variables

```bash
GRANOLA_WEBHOOK_SECRET=whsec_xxxxx   # "signing_secret", returned only once when the endpoint is created

```

## Local Development

```bash
# Start tunnel (no account needed)
npx hookdeck-cli listen 3000 granola --path /webhooks/granola

```

Use the printed URL as the endpoint URL (Settings → Connectors → Webhooks → Set up a webhook), then send a test event from the creation dialog. Respond within 15 seconds; 408, 429, 5xx and timeouts are retried for four days, other 4xx and redirects fail permanently.

## Reference Materials

* [references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/granola-webhooks/references/overview.md) - What Granola webhooks are, events, payload, delivery behaviour
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/granola-webhooks/references/setup.md) - Create an endpoint in Granola or via the API, get the signing secret
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/granola-webhooks/references/verification.md) - Signature verification details, manual Node/Python, gotchas