Webhooks

Webhooks notify your systems when notes change in Granola, so you don’t have to poll the API. You register an HTTPS URL as a webhook endpoint; when a subscribed event occurs, Granola sends it an HTTP POST with a small JSON payload, and you fetch the latest data through the Granola API. Webhooks are available on Business and Enterprise plans.

Set up a webhook endpoint

You’ll need a Granola API key. A webhook endpoint uses the same access scopes as API keys; the scopes control which notes it receives events for:

Scope	Events you’ll receive
`personal`	Notes you own, notes shared directly with you, and notes in private folders shared with you
`public`	Notes visible to everyone in the workspace

$ curl -X POST "https://public-api.granola.ai/v1/webhook-endpoints" \
  -H "Authorization: Bearer grn_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/granola-webhooks",
    "scopes": ["personal", "public"]
  }'
{
  "id": "whe_2mKr8fQxLp7Ta3",
  "object": "webhook_endpoint",
  "url": "https://example.com/granola-webhooks",
  "events": ["note.access_granted", "note.edited", "note.generated"],
  "scopes": ["personal", "public"],
  "created_by": {
    "name": "Oat Benson",
    "email": "oat@granola.ai"
  },
  "enabled": true,
  "created_at": "2026-01-27T15:30:00Z",
  "signing_secret": "whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

The signing_secret is returned only in this response and cannot be retrieved later. Store it securely. You need it to verify that deliveries came from Granola.

The URL must be HTTPS and publicly reachable; addresses on private networks are rejected. events chooses which events the endpoint receives; omit it to subscribe to all events. On Enterprise plans, workspace admins control which scopes members can use in Settings → Workspace → General → API access for members, the same controls that govern API keys.

Filter by folder

Pass folder_ids to receive events only for notes in those folders (or their subfolders), instead of every note matching scopes. Find folder IDs with List folders.

$ curl -X POST "https://public-api.granola.ai/v1/webhook-endpoints" \
  -H "Authorization: Bearer grn_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/granola-webhooks",
    "scopes": ["personal"],
    "folder_ids": ["fol_2mKr8fQxLp7Ta3"]
  }'

Make sure scopes matches the folder’s visibility: include personal for a private folder, public for a workspace-visible one.

Events

Each way a note can change has its own event. Your endpoint receives the events it subscribed to, for notes in its scope:

Event	Sent when
`note.generated`	The first AI summary for a note is generated
`note.edited`	The note’s summary is edited or regenerated
`note.access_granted`	A note is shared with you, directly or via a folder

note.generated is sent only when a note’s first summary is generated while your endpoint can access it. If an already-generated note is later shared with you, your endpoint receives note.access_granted instead. Subscribe to both events when using webhooks to discover notes. An example payload:

{
  "event_id": "8f1c2a4e-6b3d-4e8f-9a2b-1c5d7e9f0a3b",
  "event_type": "note.generated",
  "note_id": "not_1d3tmYTlCICgjy",
  "occurred_at": "2026-01-27T15:30:00Z"
}

Field	Description
`event_id`	Unique ID for the event. Retries of the same delivery reuse it.
`event_type`	Which event occurred.
`note_id`	The note the event is about. Fetch it with Get Note.
`occurred_at`	When the event occurred (ISO 8601).

note.edited payloads also include a data object with changed_fields, the note fields that changed. Currently this is always ["summary"]. Payloads carry no note content. When you receive one, fetch the note with your API key. Access checks apply at fetch time, so a delivery never exposes more than the API would.

Verify deliveries

Every delivery is signed following the Standard Webhooks specification, so you can verify it with any Standard Webhooks library, or a few lines of code.

Header	Description
`webhook-id`	The event ID (matches `event_id` in the payload)
`webhook-timestamp`	Unix timestamp, in seconds, of this delivery attempt
`webhook-signature`	`v1,` followed by a base64 HMAC-SHA256 signature

The signature is an HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{body}, keyed with your signing secret (base64-decoded, after the whsec_ prefix). Sample code for verifying it yourself:

import crypto from "crypto";

function verifyGranolaSignature(
  headers: Record<string, string>,
  rawBody: string,
  signingSecret: string
): boolean {
  const key = Buffer.from(signingSecret.slice("whsec_".length), "base64");
  const signedContent = `${headers["webhook-id"]}.${headers["webhook-timestamp"]}.${rawBody}`;
  const expected = Buffer.from(
    crypto
      .createHmac("sha256", key)
      .update(signedContent, "utf8")
      .digest("base64")
  );

  return (headers["webhook-signature"] ?? "").split(" ").some((versioned) => {
    const [version, signature = ""] = versioned.split(",");
    const provided = Buffer.from(signature);
    return (
      version === "v1" &&
      provided.length === expected.length &&
      crypto.timingSafeEqual(provided, expected)
    );
  });
}

Compute the signature over the raw request body and parse the JSON only after verifying. To protect against replayed deliveries, reject requests whose webhook-timestamp is more than a few minutes old.

Deliveries and retries

Your endpoint has 15 seconds to respond, so acknowledge with a 2xx before any heavy processing.

Response	Result
`2xx`	Delivered
`408`, `429`, `5xx`, network errors, timeouts	Retried
`3xx`	Failed permanently; redirects are not followed
Other `4xx`	Failed permanently

Failed deliveries are retried with exponential backoff for four days. Retries reuse event_id, which can be used to deduplicate deliveries. After repeated failures with no success for four days, Granola disables the endpoint and emails its creator or workspace admins. Events missed while disabled are not replayed. Restore the receiver, then re-enable the endpoint in Settings → Connectors → Webhooks.

Manage webhook endpoints

List the endpoints your key can manage. A personal key sees the endpoints you created; a workspace admin on Enterprise sees every endpoint in the workspace:

$ curl "https://public-api.granola.ai/v1/webhook-endpoints" \
  -H "Authorization: Bearer grn_YOUR_API_KEY"
{
  "webhook_endpoints": [
    {
      "id": "whe_2mKr8fQxLp7Ta3",
      "object": "webhook_endpoint",
      "url": "https://example.com/granola-webhooks",
      "events": ["note.generated"],
      "scopes": ["personal"],
      "created_by": {
        "name": "Oat Benson",
        "email": "oat@granola.ai"
      },
      "enabled": true,
      "created_at": "2026-01-27T15:30:00Z"
    }
  ]
}

created_by is null when the endpoint creator’s account was deleted.

The signing secret is never included in list responses; it’s shown once, on creation.

Delete an endpoint to stop its deliveries immediately:

$ curl -X DELETE "https://public-api.granola.ai/v1/webhook-endpoints/whe_2mKr8fQxLp7Ta3" \
  -H "Authorization: Bearer grn_YOUR_API_KEY"
{
  "id": "whe_2mKr8fQxLp7Ta3",
  "object": "webhook_endpoint",
  "deleted": true
}

See the API reference for full request and response schemas: Create webhook endpoint, List webhook endpoints, Update webhook endpoint, Delete webhook endpoint.

Overview

API Reference

Updates

Webhooks

Set up a webhook endpoint

Filter by folder

Events

Verify deliveries

Deliveries and retries

Manage webhook endpoints

​Set up a webhook endpoint

​Filter by folder

​Events

​Verify deliveries

​Deliveries and retries

​Manage webhook endpoints

Set up a webhook endpoint

Filter by folder

Events

Verify deliveries

Deliveries and retries

Manage webhook endpoints