Incoming webhooks

A webhook is a secret URL that posts messages into one channel, with no account and no connection.

On this page

Create a webhook

You need Manage Webhooks in the channel. Webhooks only post into text channels, and a channel can have up to 15.

Open the channel's settings and choose the Webhooks tab.
Enter a New webhook name (up to 80 characters; it is shown as the author of its messages) and select Create webhook.
Palloo shows the Webhook link and an Authorization header once. Copy what your service needs.

A bot with Manage Webhooks can do the same over the API with POST /channels/{id}/webhooks, which returns the webhook and its palloo_wh_ token once. Server settings, Webhooks, lists every webhook in the channels where you can manage them.

Post a message

The simplest way is the link itself:

Shell

curl -sS -X POST 'https://api.palloo.app/v1/webhooks/<webhook ID>/<token>' \
  -H 'Content-Type: application/json' \
  -d '{"content": "Build 512 passed."}'

Better, when your service lets you set headers: post to the webhook's ID alone and send the token in the Authorization header with the Webhook scheme. The token then stays out of URLs, so proxies and logs never see it:

Shell

curl -sS -X POST 'https://api.palloo.app/v1/webhooks/<webhook ID>' \
  -H "Authorization: Webhook $PALLOO_WEBHOOK_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"content": "Build 512 passed.", "username": "CI"}'

The answer is 204 with no body. Members who can see the channel receive the message at once.

Field	Meaning
`content`	The text, following the same rules as other messages (up to 4000 characters). Required unless you attach files.
`username`	A name to show on this message only, 1 to 80 characters, instead of the webhook's name.

Unknown fields are refused with 400 invalid_body, so payloads made for other services (with embeds, avatar_url or tts, for example) need changing first.

Attach files

Send multipart/form-data like Discord does: the JSON body goes in a payload_json part, and up to 10 files in parts named files[0] to files[9], each with a filename and a content type. To describe a file, list it in attachments in the JSON by its number:

Shell

curl -sS -X POST 'https://api.palloo.app/v1/webhooks/<webhook ID>' \
  -H "Authorization: Webhook $PALLOO_WEBHOOK_TOKEN" \
  -F 'payload_json={"content": "Tonight'\''s chart", "attachments": [{"id": 0, "description": "Requests per minute"}]}' \
  -F 'files[0][email protected];type=image/png'

Files count against the daily upload quota and upload limits of the person who created the webhook, and against a limit of 5 posts with files per webhook, then 1 every 12 seconds. A webhook attaches files whatever the channel's Attach Files permission says, since whoever can manage webhooks there allowed it.

How webhook messages behave

They show the webhook's name (or your username) with a webhook badge. The author is not an account and has no profile. On the gateway the message has webhook_id set and an author with kind: "webhook".
They can mention users who can see the channel and roles that are mentionable. @everyone and @here never ping.
Nobody can edit them. Members with Manage Messages can delete them.
Otherwise they are ordinary messages: unread counts, mentions, notifications and gateway events all apply.

Errors and limits

Answer	Why
`404 webhook_not_found`	No such webhook, or the token is missing or wrong. Palloo cannot tell you which.
`403 webhook_disabled`	The account that created the webhook is suspended (or, for messages with files, no longer exists).
`400 invalid_content`, `invalid_name`	The text or the `username` breaks the message or name rules.
`429 rate_limited`	Each webhook takes 5 posts at once, then 1 a second, and each address 60 at once, then 1 a second. Wait for `Retry-After` seconds.

Keep the token secret

Anyone with the link or the token can post in the channel. If it leaks, regenerate it from the channel's Webhooks tab (or with POST /webhooks/{id}/token/regenerate): the old link stops working at once. Deleting a webhook keeps the messages it already posted; deleting the channel deletes its webhooks.