Granola Webhooks Skill

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:

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:

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 and drop or widen its timestamp window.

For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.

Common Event Types

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

Environment Variables

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

Local Development

# 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 - What Granola webhooks are, events, payload, delivery behaviour
• references/setup.md - Create an endpoint in Granola or via the API, get the signing secret
• references/verification.md - Signature verification details, manual Node/Python, gotchas