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", "note.regenerated"],
  "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.

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.regenerated`	The AI summary is regenerated
`note.edited`	The note’s summary is edited
`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 webhook deliveries are retried using exponential backoff over a 24-hour period. A slow or failed response can trigger a retry for an event you already processed, so deduplicate on event_id if handling an event twice would cause problems.

Manage webhook endpoints

List the endpoints your key can manage. A personal key sees the endpoints you created; a workspace key (or 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"
    }
  ]
}

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, Delete webhook endpoint.

Overview

API Reference

Updates

Set up a webhook endpoint

Events

Verify deliveries

Deliveries and retries

Manage webhook endpoints

​Set up a webhook endpoint

​Events

​Verify deliveries

​Deliveries and retries

​Manage webhook endpoints

Set up a webhook endpoint

Events

Verify deliveries

Deliveries and retries

Manage webhook endpoints