Webhooks

Overview

Webhooks let you react to events in Grove. When something happens (article clipped, filed, read), Grove sends a signed POST request to a URL you register.

Events

- `article.created` — New article clipped to queue

- `article.filed` — Article saved to a vault folder

- `article.read` — You opened an unread article and started reading it

- `article.deleted` — Article removed

Register a Webhook

POST /api/webhooks
Authorization: Bearer grv_live_...
{
  "url": "https://your-agent.example.com/hook",
  "events": ["article.created", "article.filed"],
  "vaultPath": "Research/AI"  // optional: only fire for this folder
}

# Response includes a `secret` — save it, it's shown once and used to
# verify deliveries below.

Payload & Signature

Every delivery is a POST with the event, a timestamp, and the article. Verify it came from Grove by checking the X-Grove-Signature header — an HMAC-SHA256 of the raw body, keyed with your webhook's secret.

POST https://your-agent.example.com/hook
X-Grove-Signature: sha256=8f3b2c...

{
  "event": "article.filed",
  "timestamp": "2026-09-16T21:00:00Z",
  "vaultPath": "Research/AI",
  "article": {
    "id": "...",
    "url": "...",
    "title": "...",
    "status": "filed",
    "vaultPath": "Research/AI",
    "tags": ["ai", "research"],
    "notes": "...",
    "highlights": [{ "id": "...", "text": "...", "note": "..." }]
  }
}

Delivery is fire-and-forget — it never blocks the action that triggered it — and retries aren't queued. A subscriber that's down or slow just misses that event; check GET /api/webhooks for a hook's failureCount if deliveries seem to be dropping.

Use Cases

- Article filed to `Research/AI` → agent summarizes and cross-references your vault

- New article clipped → agent enriches metadata, suggests tags

- You start reading something → trigger an Obsidian sync or send it to another tool