How to set up CapturedIt webhooks

Webhooks let your apps react the moment your CapturedIt library changes — trigger automations, update dashboards, sync to other tools, or run custom processing when items are created or updated.

What webhooks send

When a subscribed event fires, CapturedIt POSTs JSON to your endpoint:

• event — item.created or item.updated
• item_id — the affected library item
• user_id — your account
• created_at — timestamp

Each request includes an X-CapturedIt-Signature header — an HMAC SHA-256 of the raw body using your webhook secret. Always verify before acting on the payload.

Prerequisites

• CapturedIt Vault plan (webhooks require Vault)
• A publicly reachable HTTPS endpoint (or a tunnel like ngrok for local development)
• Server code that can verify HMAC signatures

Setup steps

1. Open webhooks: Dashboard → Connections → Webhooks.
2. Enter your endpoint URL — e.g. https://your-server.com/webhooks/capturedit.
3. Select events — item.created, item.updated, or both.
4. Click Add webhook. Copy the signing secret immediately — it is shown only once.
5. Store the secret securely in your environment variables or secrets manager.
6. Implement verification in your handler before processing events.

Verify signatures (example)

Compute HMAC SHA-256 of the raw request body with your secret and compare to the header:

const crypto = require('crypto');

function verifyCapturedItWebhook(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

After verifying, call the Context Hub API to fetch full item details using item_id. See the Context Hub API guide for authentication and endpoints.

Test your webhook

1. Ensure your endpoint returns HTTP 2xx quickly (process async if needed).
2. Create a test capture in CapturedIt — a link, note, or extension save.
3. Confirm your server received item.created with a valid signature.
4. Edit the item title or content and confirm item.updated if subscribed.

Managing webhooks

• Pause / Enable: Toggle delivery without deleting the subscription.
• Regenerate secret: Rotates the signing key — update your server immediately; the old secret stops working.
• Remove: Deletes the subscription permanently.

Troubleshooting

• No deliveries: Check the endpoint is HTTPS and publicly reachable. Firewalls and localhost URLs will not receive events.
• Invalid signature: Use the raw request body (not re-serialized JSON) for HMAC. Confirm you copied the correct secret.
• Timeouts: Respond with 2xx within a few seconds; queue heavy work asynchronously.
• Vault required: Webhooks are not available on Starter or Pro without API write features — upgrade to Vault.

Frequently asked questions

Can I use Zapier instead of a custom endpoint?

Yes. Create a Zapier Catch Hook trigger and paste its URL as your webhook endpoint. Map item_id to a follow-up Context Hub API call or notification step.

Do webhooks include full item content?

Payloads are lightweight identifiers. Fetch full content via the API after verification — this keeps deliveries fast and lets you control what data leaves CapturedIt.