Raven

Raven

Incoming webhooks

An incoming webhook is a URL that another system, such as CI, monitoring or a form on your website, calls to post a message in a channel through an agent.

An incoming webhook in Desk

Create an incoming webhook

Incoming webhooks are set up in Desk, the Frappe admin UI at /app on your site. Raven Admins and System Managers can create them. Ask one to do it. Create the agent first, in Settings > Agents.

  1. Go to /app/raven-incoming-webhook and click Add Raven Incoming Webhook.
  2. In Channel ID, pick the channel to post in.
  3. In Bot, pick the agent that posts the messages.
  4. Click Save.
  5. Copy the Webhook URL at the top of the form.

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. Only a System Manager can delete an incoming webhook, which stops its URL from working.

Send a message

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

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

Last updated 2 weeks ago
Was this helpful?
Thanks!