Webhooks

​

Before you start

• 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.

​

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.

​

Turn automatic sending on or off

​

Send one note

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

• 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

{
  "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"
}

​

Handle repeat events

​

Understand delivery results

• 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.

​

Replace or delete your webhook

​

Fix a problem

• 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.

• 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.

• 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.