> ## Documentation Index
> Fetch the complete documentation index at: https://learn.cleftnotes.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Send each new Cleft note to Zapier, Make, n8n, or any service that gives you a webhook URL.

Send your new notes to Zapier, Make, n8n, or any service that gives you a webhook URL. Cleft sends each note as JSON to your webhook URL after it finishes processing the note.

> [!NOTE]
>
> **Webhooks is in preview.** It works today, and Cleft may change how it works as the feature grows. The **Preview** badge stays in Settings. Choose **Hide** to put away the note under it.

> [!NOTE]
>
> **Requires Cleft Plus.** You need an active Plus subscription to save, replace, or test a webhook and to turn on automatic sending. After a downgrade, you can still view and delete your webhook and turn sending off.

## Before you start

Copy a webhook URL from the service you want to connect. Keep the full URL private, like a password. It may contain a secret token.

* Use a long, hard-to-guess URL created only for Cleft.
* Do not paste the URL into support messages, screenshots, analytics, or public documents.
* Create a new URL in your service if you think someone else has seen it.
* Make sure your service accepts an HTTPS `POST` request that contains JSON.

Cleft checks the URL before it saves anything. The URL must start with `https://`. It cannot contain a username, a password, or a part after `#`. Addresses on your own network and other private addresses cannot receive notes. Cleft does not accept IPv6 addresses, so use a URL with a domain name, such as `hooks.example.com`.

## Connect your service

1. Open **Settings** in Cleft and choose **Integrations**.
2. On iPhone and iPad, choose **Set Up Webhook** under Webhooks. On Mac, the Webhooks section is on the Integrations page.
3. Paste your URL into **Webhook URL**. The field says **Paste your webhook URL**. Cleft hides the URL as you type. Choose **Show URL** to check it, and **Hide URL** to hide it again.
4. Choose **Save Webhook**.
5. Choose **Send Test**. Cleft shows **Test sent. Your service received it.** when your service accepts the test.
6. Turn on **Send New Notes Automatically**. The switch appears above the webhook URL once your webhook is saved, and saving sends nothing until you turn it on.

Under the switch, Cleft says: "Cleft sends each new note’s title, transcript, and text to this URL. Connect only services you trust."

After you save a webhook, the page shows **Saved URL** and hides the host name. Choose **Show Saved URL** to check it, and **Hide Saved URL** to hide it again.

## Turn automatic sending on or off

The switch appears once you save a webhook, and it starts off. While it is off, the page says "Off. Cleft sends nothing until you turn this on." While it is on, the page says "Cleft sends each new note as soon as it’s ready."

Turning the switch off keeps your webhook, so you can turn it back on later. Replacing your webhook keeps the switch as it was.

If your Plus subscription ends, Cleft pauses sending and the switch offers an upgrade. Sending resumes on its own when Plus is active again.

## Send one note

You send a single note to your webhook whenever you choose, even with **Send New Notes Automatically** off. Sending needs Plus and a saved webhook.

1. Open the note.
2. Choose **Send**.
3. Choose **Webhook**.

Cleft shows one of these messages:

* **Sent to Webhook.** Your service accepted the note.
* **Note is still processing. Try again.** Wait until the note finishes, then send it again.
* **Webhook couldn’t accept this note.** Your service answered with an error. Check your service, then send again.
* **Webhook timed out. Try again.** Your service took longer than 10 seconds to answer.
* **Too many sends. Try again soon.** Wait a minute before sending again.

## What Cleft sends

Cleft sends one `note_ready` event when a new note first finishes processing. The event contains the note's text and timestamps:

```json theme={null}
{
  "event_id": "00000000-0000-4000-8000-000000000264",
  "event_type": "note_ready",
  "occurred_at": "2026-08-04T12:00:00.000Z",
  "note_id": 1234,
  "title": "Cleft Webhook Test",
  "transcript": "This is synthetic sample transcript content from Cleft.",
  "ai_summary": "## Cleft Webhook Test\n\nThis is synthetic sample note content from Cleft.",
  "markdown": "## Cleft Webhook Test\n\nThis is synthetic sample note content from Cleft.",
  "plain_text": "Cleft Webhook Test\n\nThis is synthetic sample note content from Cleft.",
  "processing_status": "processed",
  "created_at": "2026-08-04T12:00:00.000Z",
  "updated_at": "2026-08-04T12:00:00.000Z"
}
```

The example and the test use made-up content, not one of your notes. Automatic events contain the finished note's title, transcript, note text, plain text, and timestamps. They do not contain your email address, audio, attachments, storage links, or account details.

To see the example in the app, open **See What Cleft Sends**. Choose **Copy Example** to copy it.

## Handle repeat events

Use `event_id` to spot repeats. Cleft keeps the same ID when it retries one event, so your service can ignore an event it already accepted.

Cleft delivers at least once, not exactly once. An event may arrive more than once or out of order. Set up your automation so a repeat does no harm.

## Understand delivery results

Your service tells Cleft it accepted an event by sending any `2xx` response. Cleft retries temporary network failures, timeouts, rate limits, and server errors, with a longer wait between tries. It stops after five attempts or 24 hours, whichever comes first.

Redirects and most other `4xx` responses are final. Cleft does not retry them. Fix the problem in your service, then replace the webhook in Settings if the URL changed.

**Send Test** makes one attempt and waits for your service to answer. Your service has 10 seconds to respond. A slow service that accepts the test still counts as delivered. The page shows one of these messages:

* **Test sent. Your service received it.** Your service sent a `2xx` response.
* **Your service didn’t accept the test. Check the URL and try again.** Your service sent a final response, or Cleft could not use the URL safely.
* **Your service didn’t answer in time. Try again in a moment.** Your service did not finish in time.

The page keeps the latest result as **Last test**, for example "Last test: Delivered · 2:15 PM". The result is one of **Delivered**, **Not accepted**, **Timed out**, or **Failed**.

## Replace or delete your webhook

To replace your webhook, enter the new URL and choose **Replace Webhook**. Cleft asks you to confirm in **Replace Webhook URL?**, because future notes go to the new URL. Cleft checks that you have the latest saved version first, so another device cannot overwrite a newer change by accident.

To stop sending and remove your webhook, choose **Delete Webhook** at the bottom of the page. Confirm in **Delete Webhook?**. Deleting does not take back notes that your service or another service already received. Use that service's controls to delete or limit what it keeps.

## Fix a problem

When something goes wrong, Cleft keeps the URL you typed so you can try again. Cleft also tells you what happened:

* **Webhooks is temporarily unavailable. Nothing changed. Try again in a few minutes.** The problem is on Cleft's side, not with your service. You also see this when Cleft cannot confirm your Plus subscription or cannot look up your URL's domain name.
* **Cleft couldn’t save that change. Your webhook and the URL you entered are unchanged.** The change failed. Check the URL and try again.
* **You made several changes in a short time. Nothing changed. Try again in a few minutes.** Wait a few minutes. Nothing else helps.
* **Webhooks needs Plus. Upgrade to continue.** Your account needs Plus. Cleft offers the upgrade on the same page.
* **Cleft is still checking your Plus subscription. Try again in a moment.**
* **Your webhook changed on another device. Reload it, then save again. The URL you entered is still here.** Choose **Reload Webhook**, review the current webhook, then decide whether to replace it. You also see this when you delete or test a webhook that another device already changed.
* **Cleft couldn’t load your webhook settings. Try again to make changes.** Choose **Try Again**. Cleft does not treat your URL as saved until it confirms the save.
* **Webhook setup is paused for now. You can still turn off sending or delete your webhook.** Cleft has paused setup for a while. Turn off **Send New Notes Automatically** or choose **Delete Webhook** if you need to.

After a failed load, Cleft waits a minute before it checks again on its own. Opening Settings again during an outage does not repeat the same failed request. **Try Again** always checks right away.

If Cleft rejects the URL you entered, the page says what to fix:

* **Enter a webhook URL.** The field is empty.
* **This URL is too long.** Use a shorter URL.
* **Enter the full URL, starting with https\://.** The URL is incomplete.
* **The URL must start with https\://.** Cleft accepts only HTTPS.
* **Remove the username or password from the URL.**
* **Remove the part after # from the URL.**
* **Use a URL from an online service. Addresses on your own network can’t receive notes.**
* **Use a URL from an online service. Private network addresses can’t receive notes.**
* **Use a URL with a domain name, such as hooks.example.com.** Cleft does not accept IPv6 addresses.

If the problem is with your service:

* **The test is not accepted:** Check the HTTPS method, the access token, and the response status in your service. Do not share the full URL while you check.
* **The test times out:** Make sure your service answers within 10 seconds and does not redirect the request.
* **Someone else may have seen your URL:** Create a new URL in your service, replace the webhook in Cleft, and delete the old URL in your service.

When you contact [Cleft Support](https://learn.cleftnotes.com/user-guides/contact-support.md), share the result and the approximate time. Never send the full webhook URL, a real note, access tokens, or your service's response.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.