Webhooks API

List channel webhooks

GET /channels/{id}/webhooks Bot token

The channel's webhooks. Requires Manage Webhooks in the channel.

Required permissions

Requires Manage Webhooks in the channel.

Try it

Sends the bot token from the top of this page.

Parameters

id (path, required)

Request

GET https://api.palloo.app/v1/channels/{id}/webhooks

Include my token in the copied command

curl command

Response

Parameters

Parameters of List channel webhooks
Name	In	Type	Description
id Required	path	string	Channel ID.

Responses

200

The webhooks, oldest first. Tokens are never listed.

Body: WebhookList

Example response (200)

{
  "webhooks": [
    {
      "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
      "channel_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
      "community_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
      "name": "string",
      "created_by": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
      "created_at": "2026-10-15T09:00:00Z"
    }
  ]
}

401

unauthenticated: the bearer token is missing, invalid or expired.

Body: Error

WWW-Authenticate header.

403

missing_permission: the caller is a member but lacks the permission.

Body: Error

404

channel_not_found: no such channel, or the caller is not a member of its community or cannot view the channel.

Body: Error

429

rate_limited: too many attempts. Every operation a bot calls is also limited per bot (50 at once, then 50 per second), so any authenticated operation can answer this to a bot. Changes to a community's structure (creating or changing the community, channels, roles, member roles, overwrites, invites, kicks, bans, timeouts, report updates and actions, and bots) are also limited per caller (30 at once, then 1 per second) and per community (60 at once, then 1 per second), and creating communities per caller (10 at once, then 1 every 5 minutes).

Body: Error

Retry-After header.

500

internal: an unexpected server error. Details are only in server logs.

Body: Error

Create webhook

POST /channels/{id}/webhooks Bot token

Create a webhook on a text channel. Requires Manage Webhooks in the channel. Returns its token, once.

At most 15 webhooks per channel. Post with POST /webhooks/{id}/{token}; the token starts with palloo_wh_ and is never shown again.

Required permissions

Requires Manage Webhooks in the channel.

Try it

Sends the bot token from the top of this page.

Parameters

id (path, required)

Request body (JSON, required)

Prefilled from the example above. Replace the placeholder values; unknown fields are refused.

Request

POST https://api.palloo.app/v1/channels/{id}/webhooks

Include my token in the copied command

curl command

Response

Parameters

Parameters of Create webhook
Name	In	Type	Description
id Required	path	string	Channel ID.

Request body

application/json: WebhookNameRequest (required)

Fields of the application/json request body
Field	Type	Description
nameRequired	string	1-80 characters, the same rules as other names.

Example request body

{
  "name": "string"
}

Responses

201

The webhook and its token.

Body: WebhookWithToken

Cache-Control header.

Example response (201)

{
  "webhook": {
    "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "channel_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "community_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "name": "string",
    "created_by": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "created_at": "2026-10-15T09:00:00Z"
  },
  "token": "palloo_wh_..."
}

400

invalid_body, invalid_name or name_reserved (a reserved webhook name, unless its creator is an instance admin).

Body: Error

401

unauthenticated: the bearer token is missing, invalid or expired.

Body: Error

WWW-Authenticate header.

403

missing_permission: the caller is a member but lacks the permission, or mfa_sudo_required: the account has MFA and this session has not verified a factor in the last 5 minutes (POST /users/@me/mfa/sudo, then retry).

Body: Error

404

channel_not_found: no such channel, or the caller is not a member of its community or cannot view the channel.

Body: Error

409

channel_not_text or webhook_limit_reached.

Body: Error

429

rate_limited: too many attempts. Every operation a bot calls is also limited per bot (50 at once, then 50 per second), so any authenticated operation can answer this to a bot. Changes to a community's structure (creating or changing the community, channels, roles, member roles, overwrites, invites, kicks, bans, timeouts, report updates and actions, and bots) are also limited per caller (30 at once, then 1 per second) and per community (60 at once, then 1 per second), and creating communities per caller (10 at once, then 1 every 5 minutes).

Body: Error

Retry-After header.

500

internal: an unexpected server error. Details are only in server logs.

Body: Error

List community webhooks

GET /communities/{id}/webhooks Bot token

The community's webhooks in the channels where the caller has Manage Webhooks.

Requires Manage Webhooks as a community permission (from roles).

Required permissions

Requires Manage Webhooks as a community permission (from roles).

Try it

Sends the bot token from the top of this page.

Parameters

id (path, required)

Request

GET https://api.palloo.app/v1/communities/{id}/webhooks

Include my token in the copied command

curl command

Response

Parameters

Parameters of List community webhooks
Name	In	Type	Description
id Required	path	string	Community ID.

Responses

200

The webhooks, oldest first.

Body: WebhookList

Example response (200)

{
  "webhooks": [
    {
      "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
      "channel_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
      "community_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
      "name": "string",
      "created_by": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
      "created_at": "2026-10-15T09:00:00Z"
    }
  ]
}

401

unauthenticated: the bearer token is missing, invalid or expired.

Body: Error

WWW-Authenticate header.

403

missing_permission: the caller is a member but lacks the permission.

Body: Error

404

community_not_found: no such community, or the caller is not a member. The two cases are indistinguishable on purpose.

Body: Error

429

rate_limited: too many attempts. Every operation a bot calls is also limited per bot (50 at once, then 50 per second), so any authenticated operation can answer this to a bot. Changes to a community's structure (creating or changing the community, channels, roles, member roles, overwrites, invites, kicks, bans, timeouts, report updates and actions, and bots) are also limited per caller (30 at once, then 1 per second) and per community (60 at once, then 1 per second), and creating communities per caller (10 at once, then 1 every 5 minutes).

Body: Error

Retry-After header.

500

internal: an unexpected server error. Details are only in server logs.

Body: Error

Execute webhook with header

POST /webhooks/{id} Webhook token

Post a message as the webhook, with the token in the Authorization header.

The same as POST /webhooks/{id}/{token}, but the token travels as Authorization: Webhook <token> instead of in the URL, so proxies and logs never see it. A missing or wrong token is the same 404 as an unknown webhook. Rate limited per webhook (5 at once, then 1 per second) and per client address.

Try it

Webhook token

Sent as Authorization: Webhook ... instead of the bot token. It is a password too, and is forgotten with the bot token.

Parameters

id (path, required)

Request body (JSON, required)

Prefilled from the example above. Replace the placeholder values; unknown fields are refused.

Request

POST https://api.palloo.app/v1/webhooks/{id}

Include my token in the copied command

curl command

Response

Parameters

Parameters of Execute webhook with header
Name	In	Type	Description
id Required	path	string	Webhook ID.

Request body

application/json: ExecuteWebhookRequest (required)

Fields of the application/json request body
Field	Type	Description
content	string	Required unless files are attached.
username	string	A name for this message only, 1-80 characters, the same rules as other names.
message_reference	ReplyReference	Posts the message as a reply to a message in the webhook's channel, as for `sendMessage` (a webhook needs no Read Message History). Refused with `replies_disabled` (403) while the `replies` flag is off for the server, and with `invalid_reference`, `reference_not_found` or `system_message` (400) as for `sendMessage`.
allowed_mentions	AllowedMentions
attachments	array of object	Only with multipart. Describes the files by their `files[n]` number.
attachments[].idRequired	integer	at least 0; at most 9
attachments[].description	string
attachments[].filename	string	A display name to use instead of the part's; the stored extension stays, as for `AttachmentRef`.

Example request body

{
  "content": "string",
  "username": "string",
  "message_reference": {
    "message_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "channel_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "fail_if_not_exists": true
  },
  "allowed_mentions": {
    "replied_user": false
  },
  "attachments": [
    {
      "id": 0,
      "description": "string",
      "filename": "string"
    }
  ]
}

multipart/form-data: ExecuteWebhookMultipart (required)

Fields of the multipart/form-data request body
Field	Type	Description
payload_json	string
files[0]	string (binary)
files[1]	string (binary)
files[2]	string (binary)
files[3]	string (binary)
files[4]	string (binary)
files[5]	string (binary)
files[6]	string (binary)
files[7]	string (binary)
files[8]	string (binary)
files[9]	string (binary)

Responses

204

Posted. Members receive message_create.

400

invalid_body, invalid_content, invalid_name (the username override), name_reserved (a reserved username override other than the webhook's own name), or for files invalid_upload, too_many_attachments, invalid_attachment (an attachments entry names no file part), invalid_description, content_type_mismatch, invalid_image, image_too_large, upload_rejected or upload_malware (the file was blocked as malware). Files are charged to the webhook creator's daily upload quota (429 upload_quota_exceeded) and upload rate limit, and to a per-webhook upload limit (5 requests with files, then 1 every 12 seconds).

Body: Error

403

webhook_disabled: the webhook's creator is suspended (any message), or the creator no longer has an account (messages with files, which are charged to the creator).

Body: Error

404

webhook_not_found: no such webhook, or the token is missing or wrong. These are indistinguishable.

Body: Error

413

file_too_large: a file is larger than media.max_upload_bytes; the message says the limit.

Body: Error

429

rate_limited: too many attempts. Every operation a bot calls is also limited per bot (50 at once, then 50 per second), so any authenticated operation can answer this to a bot. Changes to a community's structure (creating or changing the community, channels, roles, member roles, overwrites, invites, kicks, bans, timeouts, report updates and actions, and bots) are also limited per caller (30 at once, then 1 per second) and per community (60 at once, then 1 per second), and creating communities per caller (10 at once, then 1 every 5 minutes).

Body: Error

Retry-After header.

500

internal: an unexpected server error. Details are only in server logs.

Body: Error

503

storage_unavailable, scan_unavailable or upload_processing (the image decoders are busy); send again later.

Body: Error

Retry-After header.

Rename webhook

PATCH /webhooks/{id} Bot token

Rename a webhook. Requires Manage Webhooks in its channel. Past messages keep their name.

Required permissions

Requires Manage Webhooks in its channel.

Try it

Sends the bot token from the top of this page.

Parameters

id (path, required)

Request body (JSON, required)

Prefilled from the example above. Replace the placeholder values; unknown fields are refused.

Request

PATCH https://api.palloo.app/v1/webhooks/{id}

Include my token in the copied command

curl command

Response

Parameters

Parameters of Rename webhook
Name	In	Type	Description
id Required	path	string	Webhook ID.

Request body

application/json: WebhookNameRequest (required)

Fields of the application/json request body
Field	Type	Description
nameRequired	string	1-80 characters, the same rules as other names.

Example request body

{
  "name": "string"
}

Responses

200

The renamed webhook.

Body: Webhook

Example response (200)

{
  "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "channel_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "community_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "name": "string",
  "created_by": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
  "created_at": "2026-10-15T09:00:00Z"
}

400

invalid_body, invalid_name or name_reserved (a reserved webhook name, unless its creator is an instance admin).

Body: Error

401

unauthenticated: the bearer token is missing, invalid or expired.

Body: Error

WWW-Authenticate header.

403

missing_permission: the caller is a member but lacks the permission.

Body: Error

404

webhook_not_found: no such webhook, or the caller cannot view its channel.

Body: Error

429

rate_limited: too many attempts. Every operation a bot calls is also limited per bot (50 at once, then 50 per second), so any authenticated operation can answer this to a bot. Changes to a community's structure (creating or changing the community, channels, roles, member roles, overwrites, invites, kicks, bans, timeouts, report updates and actions, and bots) are also limited per caller (30 at once, then 1 per second) and per community (60 at once, then 1 per second), and creating communities per caller (10 at once, then 1 every 5 minutes).

Body: Error

Retry-After header.

500

internal: an unexpected server error. Details are only in server logs.

Body: Error

Delete webhook

DELETE /webhooks/{id} Bot token

Delete a webhook. Requires Manage Webhooks in its channel. Its messages stay.

Required permissions

Requires Manage Webhooks in its channel.

Try it

Sends the bot token from the top of this page.

Parameters

id (path, required)

Request

DELETE https://api.palloo.app/v1/webhooks/{id}

Include my token in the copied command

curl command

Response

Parameters

Parameters of Delete webhook
Name	In	Type	Description
id Required	path	string	Webhook ID.

Responses

204

Deleted.

401

unauthenticated: the bearer token is missing, invalid or expired.

Body: Error

WWW-Authenticate header.

403

missing_permission: the caller is a member but lacks the permission.

Body: Error

404

webhook_not_found: no such webhook, or the caller cannot view its channel.

Body: Error

429

rate_limited: too many attempts. Every operation a bot calls is also limited per bot (50 at once, then 50 per second), so any authenticated operation can answer this to a bot. Changes to a community's structure (creating or changing the community, channels, roles, member roles, overwrites, invites, kicks, bans, timeouts, report updates and actions, and bots) are also limited per caller (30 at once, then 1 per second) and per community (60 at once, then 1 per second), and creating communities per caller (10 at once, then 1 every 5 minutes).

Body: Error

Retry-After header.

500

internal: an unexpected server error. Details are only in server logs.

Body: Error

Regenerate webhook token

POST /webhooks/{id}/token/regenerate Bot token

Replace a webhook's token. Requires Manage Webhooks in its channel. The old URL stops working.

Required permissions

Requires Manage Webhooks in its channel.

Try it

Sends the bot token from the top of this page.

Parameters

id (path, required)

Request

POST https://api.palloo.app/v1/webhooks/{id}/token/regenerate

Include my token in the copied command

curl command

Response

Parameters

Parameters of Regenerate webhook token
Name	In	Type	Description
id Required	path	string	Webhook ID.

Responses

200

The webhook and its new token.

Body: WebhookWithToken

Cache-Control header.

Example response (200)

{
  "webhook": {
    "id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "channel_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "community_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "name": "string",
    "created_by": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "created_at": "2026-10-15T09:00:00Z"
  },
  "token": "palloo_wh_..."
}

401

unauthenticated: the bearer token is missing, invalid or expired.

Body: Error

WWW-Authenticate header.

403

missing_permission: the caller is a member but lacks the permission, or mfa_sudo_required: the account has MFA and this session has not verified a factor in the last 5 minutes (POST /users/@me/mfa/sudo, then retry).

Body: Error

404

webhook_not_found: no such webhook, or the caller cannot view its channel.

Body: Error

429

rate_limited: too many attempts. Every operation a bot calls is also limited per bot (50 at once, then 50 per second), so any authenticated operation can answer this to a bot. Changes to a community's structure (creating or changing the community, channels, roles, member roles, overwrites, invites, kicks, bans, timeouts, report updates and actions, and bots) are also limited per caller (30 at once, then 1 per second) and per community (60 at once, then 1 per second), and creating communities per caller (10 at once, then 1 every 5 minutes).

Body: Error

Retry-After header.

500

internal: an unexpected server error. Details are only in server logs.

Body: Error

Execute webhook

POST /webhooks/{id}/{token} No token

Post a message as the webhook. No other authentication.

Prefer POST /webhooks/{id} with Authorization: Webhook <token>, which keeps the token out of URLs. content follows the message rules. username replaces the webhook's name on this message only. Mentions of users who can view the channel and of mentionable roles ping; @everyone and @here never do. Rate limited per webhook (5 at once, then 1 per second) and per client address.

Try it

Sends no bot token.

Parameters

id (path, required)

token (path, required)

A secret: hidden in the headers preview and replaced by $PALLOO_WEBHOOK_TOKEN in the copied command.

Request body (JSON, required)

Prefilled from the example above. Replace the placeholder values; unknown fields are refused.

Request

POST https://api.palloo.app/v1/webhooks/{id}/{token}

Include my token in the copied command

curl command

Response

Parameters

Parameters of Execute webhook
Name	In	Type	Description
id Required	path	string	Webhook ID.
token Required	path	string	The webhook's token.

Request body

application/json: ExecuteWebhookRequest (required)

Fields of the application/json request body
Field	Type	Description
content	string	Required unless files are attached.
username	string	A name for this message only, 1-80 characters, the same rules as other names.
message_reference	ReplyReference	Posts the message as a reply to a message in the webhook's channel, as for `sendMessage` (a webhook needs no Read Message History). Refused with `replies_disabled` (403) while the `replies` flag is off for the server, and with `invalid_reference`, `reference_not_found` or `system_message` (400) as for `sendMessage`.
allowed_mentions	AllowedMentions
attachments	array of object	Only with multipart. Describes the files by their `files[n]` number.
attachments[].idRequired	integer	at least 0; at most 9
attachments[].description	string
attachments[].filename	string	A display name to use instead of the part's; the stored extension stays, as for `AttachmentRef`.

Example request body

{
  "content": "string",
  "username": "string",
  "message_reference": {
    "message_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "channel_id": "01J9ZQ3V5K8M2N4P6R8T0W2Y4A",
    "fail_if_not_exists": true
  },
  "allowed_mentions": {
    "replied_user": false
  },
  "attachments": [
    {
      "id": 0,
      "description": "string",
      "filename": "string"
    }
  ]
}

multipart/form-data: ExecuteWebhookMultipart (required)

Fields of the multipart/form-data request body
Field	Type	Description
payload_json	string
files[0]	string (binary)
files[1]	string (binary)
files[2]	string (binary)
files[3]	string (binary)
files[4]	string (binary)
files[5]	string (binary)
files[6]	string (binary)
files[7]	string (binary)
files[8]	string (binary)
files[9]	string (binary)

Responses

204

Posted. Members receive message_create.

400

invalid_body, invalid_content, invalid_name (the username override), name_reserved (a reserved username override other than the webhook's own name), or for files invalid_upload, too_many_attachments, invalid_attachment (an attachments entry names no file part), invalid_description, content_type_mismatch, invalid_image, image_too_large, upload_rejected or upload_malware (the file was blocked as malware). Files are charged to the webhook creator's daily upload quota (429 upload_quota_exceeded) and upload rate limit, and to a per-webhook upload limit (5 requests with files, then 1 every 12 seconds).

Body: Error

403

webhook_disabled: the webhook's creator is suspended (any message), or the creator no longer has an account (messages with files, which are charged to the creator).

Body: Error

404

webhook_not_found: no such webhook, or the token is wrong. The two are indistinguishable.

Body: Error

413

file_too_large: a file is larger than media.max_upload_bytes; the message says the limit.

Body: Error

429

rate_limited: too many attempts. Every operation a bot calls is also limited per bot (50 at once, then 50 per second), so any authenticated operation can answer this to a bot. Changes to a community's structure (creating or changing the community, channels, roles, member roles, overwrites, invites, kicks, bans, timeouts, report updates and actions, and bots) are also limited per caller (30 at once, then 1 per second) and per community (60 at once, then 1 per second), and creating communities per caller (10 at once, then 1 every 5 minutes).

Body: Error

Retry-After header.

500

internal: an unexpected server error. Details are only in server logs.

Body: Error

503

storage_unavailable, scan_unavailable or upload_processing (the image decoders are busy); send again later.

Body: Error

Retry-After header.