---
title: "Incoming webhooks"
space: "Raven"
url: "https://docs.frappe.io/raven/agents-and-webhooks/incoming-webhooks"
updated: "2026-10-19"
---

An incoming webhook is a URL that another system calls to post a message in Raven. The message is posted by an [agent](wiki:6e7bbec94d65) in the channel you choose.

Use it for alerts from tools such as CI, monitoring or a form on your website.

## Create an incoming webhook

Incoming webhooks are set up in Desk, the Frappe admin UI at `/app` on your site. Create the [agent](wiki:6e7bbec94d65) first, in **Settings > Agents**.

1. Go to `/app/raven-incoming-webhook` on your site.
2. Click **Add Raven Incoming Webhook**.
3. In **Channel ID**, pick the channel to post in.
4. In **Bot**, pick the agent that posts the messages.
5. Click **Save**.
6. Copy the **Webhook URL**. It shows at the top of the form after you save.

<picture>
  <source srcset="/files/raven-dark-bots-incoming-webhook.webp" media="(prefers-color-scheme: dark)">
  <img src="/files/raven-light-bots-incoming-webhook.webp" alt="An incoming webhook in Desk" width="595">
</picture>

The URL looks like this:

```
https://your-site.com/api/method/raven.webhook/<webhook ID>
```

The webhook ID is a long random string. Anyone who has the URL can post in the channel, so keep it secret.

:::note
Raven admins and System Managers can create incoming webhooks. Only System Managers can delete them. Deleting a webhook stops its URL from working.
:::

## Send a message

Send a `POST` request to the webhook URL with a JSON body. Put the message in the `content` field. Write it in Markdown.

```bash
curl -X POST "https://your-site.com/api/method/raven.webhook/<webhook ID>" \
  -H "Content-Type: application/json" \
  -d '{"content": "**Deploy finished.** Version 2.4 is live."}'
```

The `Content-Type: application/json` header is required.

Raven ignores every field other than `content`. If `content` is missing or empty, Raven posts an empty message.

## Responses

| Status | Body | Meaning |
| :--- | :--- | :--- |
| 201 | `ok` | The message was posted. |
| 400 | `POST request expected` | The request was a `GET`. |
| 400 | `json expected` | The body is not JSON, or the `Content-Type` header is not `application/json`. |
| 400 | `dict expected` | The JSON is not an object, for example a list or a string. |
| 404 | `webhook not found` | No incoming webhook has this ID. |

Error bodies are JSON, with the text in a `message` field: `{"message": "webhook not found"}`.