Incoming webhooks

An incoming webhook is a URL that another system calls to post a message in Raven. The message is posted by an agent 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 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.

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.

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.

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

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