GRgranola

Create webhook endpoint

Changed on

Registers an HTTPS URL to receive event deliveries. With a Workspace API key the endpoint is workspace-managed: pass scopes: ["workspace"] (the key's own scope), and folder_ids may only reference folders the key can list.

post/v1/webhook-endpoints

Request

  • Base URL
    https://public-api.granola.ai
  • Auth
    HTTP bearer

Request body

urlstring uri required

The publicly reachable HTTPS URL to deliver events to

scopesstring[] required

Which notes to receive events for. personal covers notes you own, notes shared directly with you, and notes in private folders shared with you. public covers notes visible to everyone in the workspace. Pass both for both sets of notes. Workspace admins can disable scopes for non-admin members in the workspace's API settings. With a Workspace API key, pass exactly ["workspace"] — the key's own scope: public workspace notes plus notes in spaces with Granola API access enabled.

eventsstring[]

Event names to subscribe to. Omit to subscribe to all events.

folder_idsstring[]

Restrict delivery to notes in these folders or any of their subfolders. Accepts folder IDs returned by GET /v1/folders, in any casing. Omit to receive events for every note matching scopes. The same filter applies to all subscribed events.

Example request

{
  "url": "https://example.com/granola-webhooks",
  "scopes": [
    "personal",
    "public"
  ],
  "events": [
    "note.access_granted",
    "note.edited",
    "note.generated"
  ],
  "folder_ids": [
    "fol_2mKr8fQxLp7Ta3"
  ]
}

Response

Webhook endpoint created. The signing secret is only returned here.

idstring required

The ID of the webhook endpoint

object'webhook_endpoint' required
urlstring uri required

The HTTPS URL deliveries are sent to. When url_redacted is true, reduced to the URL's origin.

url_redactedboolean required

True when this response reduces url to its origin because the caller is not the endpoint's creator (the path can carry credentials). Orphaned endpoints whose creator account was deleted are returned unredacted so they can be cleaned up.

eventsstring[] required

The event names this endpoint is subscribed to

folder_idsstring[] required

Folder IDs this endpoint's delivery is restricted to, or an empty array when unrestricted. Events fire only for notes in these folders or their subfolders.

scopesstring[] required

Which notes this endpoint receives events for. personal covers notes the creating user owns, notes shared directly with them, and notes in private folders shared with them. public covers notes visible to everyone in the workspace. workspace is reported for endpoints created with a workspace API key: public workspace notes plus notes in spaces with Granola API access enabled.

enabledboolean required

Whether deliveries are active

created_atstring date-time required

The creation time of the webhook endpoint

signing_secretstring required

Secret for verifying delivery signatures (Standard Webhooks HMAC-SHA256). Shown only once, in this response — store it securely.

Example response

{
  "id": "whe_2mKr8fQxLp7Ta3",
  "url": "https://example.com/granola-webhooks",
  "events": [
    "note.access_granted",
    "note.edited",
    "note.generated"
  ],
  "folder_ids": [],
  "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"
}

Changes

  • 480617fbc624Revision changes
    • warning

      changed the pattern of the request property / from ^fol_[a-zA-Z0-9]{14}$ to ^[Ff][Oo][Ll]_[a-zA-Z0-9]{14}$

  • 150856520accRevision changes
    • breaking

      removed the enum value note.regenerated of the request property /

    • info

      the request property default value changed from note.access_granted note.edited note.generated note.regenerated to note.access_granted note.edited note.generated

    • info

      removed the note.regenerated enum value from the ///// response property for the response status