Webhooks: manage channel webhooks with the bot token, send and edit messages through a webhook's own token (no bot token needed), and verify Discord's Ed25519-signed interaction and event requests.

Functions

create-webhook

fn (request: CreateWebhookRequest): Map
fn (request: CreateWebhookRequest, opts: Map): Map

POST /channels/{channel_id}/webhooks - Create a webhook (name 1-80 characters; avatar is a data URI). The result carries the token used by execute-webhook. Needs MANAGE_WEBHOOKS.

Example

::webhooks ::discord::webhooks

hook ::webhooks/create-webhook(::webhooks/CreateWebhookRequest({
  channel_id: "1100000000000000000",
  name: "Hot Notifications"
}))
hook.token

delete-webhook

fn (request: DeleteWebhookRequest): Bool
fn (request: DeleteWebhookRequest, opts: Map): Bool

DELETE /webhooks/{webhook_id} - Delete a webhook. Needs MANAGE_WEBHOOKS.

Example

::webhooks ::discord::webhooks

::webhooks/delete-webhook(::webhooks/DeleteWebhookRequest({
  webhook_id: "1600000000000000000",
  reason: "Rotating integrations"
}))

delete-webhook-message

fn (request: DeleteWebhookMessageRequest): Bool
fn (request: DeleteWebhookMessageRequest, opts: Map): Bool

DELETE /webhooks/{webhook_id}/{webhook_token}/messages/{message_id} - Delete a message this webhook sent.

Example

::webhooks ::discord::webhooks

::webhooks/delete-webhook-message(::webhooks/DeleteWebhookMessageRequest({
  webhook_id: "1600000000000000000",
  webhook_token: ::hot::ctx/get("discord.webhook.token"),
  message_id: "1200000000000000000"
}))

delete-webhook-with-token

fn (request: DeleteWebhookWithTokenRequest): Bool
fn (request: DeleteWebhookWithTokenRequest, opts: Map): Bool

DELETE /webhooks/{webhook_id}/{webhook_token} - Delete a webhook using its token.

Example

::webhooks ::discord::webhooks

::webhooks/delete-webhook-with-token(::webhooks/DeleteWebhookWithTokenRequest({
  webhook_id: "1600000000000000000",
  webhook_token: ::hot::ctx/get("discord.webhook.token")
}))

edit-webhook-message

fn (request: EditWebhookMessageRequest): Map
fn (request: EditWebhookMessageRequest, opts: Map): Map

PATCH /webhooks/{webhook_id}/{webhook_token}/messages/{message_id} - Edit a message this webhook sent. Only fields you set are sent. attachments is the full list to keep; new files are appended.

Example

::webhooks ::discord::webhooks

::webhooks/edit-webhook-message(::webhooks/EditWebhookMessageRequest({
  webhook_id: "1600000000000000000",
  webhook_token: ::hot::ctx/get("discord.webhook.token"),
  message_id: "1200000000000000000",
  content: "Deploy complete (edited)"
}))

execute-webhook

fn (request: ExecuteWebhookRequest): Map?
fn (request: ExecuteWebhookRequest, opts: Map): Map?

POST /webhooks/{webhook_id}/{webhook_token} - Send a message through a webhook. No bot token needed. Returns the message when wait: true, otherwise null (204). Provide at least one of content, embeds, components, poll or files.

  • thread_id posts into a thread; in a forum or media channel pass thread_name (and optional applied_tags) to create a post instead.
  • username / avatar_url override the webhook's identity per message.
  • with_components: true is needed for components on a webhook your app doesn't own (non-interactive components only).
  • files uploads attachments (multipart); refer to one in an embed as attachment://<filename>.

Example

::webhooks ::discord::webhooks

msg ::webhooks/execute-webhook(::webhooks/ExecuteWebhookRequest({
  webhook_id: "1600000000000000000",
  webhook_token: "webhook-token",
  content: "Deploy complete",
  embeds: [{title: "v2.1.0", color: 3066993}],
  wait: true
}))
msg.id

get-channel-webhooks

fn (request: GetChannelWebhooksRequest): Vec<Map>
fn (request: GetChannelWebhooksRequest, opts: Map): Vec<Map>

GET /channels/{channel_id}/webhooks - Webhooks in a channel. Needs MANAGE_WEBHOOKS.

Example

::webhooks ::discord::webhooks

hooks ::webhooks/get-channel-webhooks(::webhooks/GetChannelWebhooksRequest({channel_id: "1100000000000000000"}))
map(hooks, %.name)

get-guild-webhooks

fn (request: GetGuildWebhooksRequest): Vec<Map>
fn (request: GetGuildWebhooksRequest, opts: Map): Vec<Map>

GET /guilds/{guild_id}/webhooks - Webhooks in a guild. Needs MANAGE_WEBHOOKS.

Example

::webhooks ::discord::webhooks

hooks ::webhooks/get-guild-webhooks(::webhooks/GetGuildWebhooksRequest({guild_id: "1000000000000000000"}))
map(hooks, %.channel_id)

get-webhook

fn (request: GetWebhookRequest): Map
fn (request: GetWebhookRequest, opts: Map): Map

GET /webhooks/{webhook_id} - A webhook by id. Needs MANAGE_WEBHOOKS.

Example

::webhooks ::discord::webhooks

hook ::webhooks/get-webhook(::webhooks/GetWebhookRequest({webhook_id: "1600000000000000000"}))
hook.name

get-webhook-message

fn (request: GetWebhookMessageRequest): Map
fn (request: GetWebhookMessageRequest, opts: Map): Map

GET /webhooks/{webhook_id}/{webhook_token}/messages/{message_id} - A message this webhook sent. Pass thread_id for messages in a thread.

Example

::webhooks ::discord::webhooks

message ::webhooks/get-webhook-message(::webhooks/GetWebhookMessageRequest({
  webhook_id: "1600000000000000000",
  webhook_token: ::hot::ctx/get("discord.webhook.token"),
  message_id: "1200000000000000000"
}))
message.content

get-webhook-with-token

fn (request: GetWebhookWithTokenRequest): Map
fn (request: GetWebhookWithTokenRequest, opts: Map): Map

GET /webhooks/{webhook_id}/{webhook_token} - A webhook, authenticated by its token (no bot token, no user field).

Example

::webhooks ::discord::webhooks

hook ::webhooks/get-webhook-with-token(::webhooks/GetWebhookWithTokenRequest({
  webhook_id: "1600000000000000000",
  webhook_token: ::hot::ctx/get("discord.webhook.token")
}))
hook.channel_id

mark-webhook-tokens

fn (value: Any): Any

Mask the token of a webhook object, or of each in a Vec, in call records. Returns value unchanged. Exposed for testing.

Example

::discord::webhooks/mark-webhook-tokens({id: "1", token: "abc"})  // {id: "1", token: "abc"}

modify-webhook

fn (request: ModifyWebhookRequest): Map
fn (request: ModifyWebhookRequest, opts: Map): Map

PATCH /webhooks/{webhook_id} - Rename a webhook, change its avatar, or move it to channel_id. Only fields you set are sent; clear: ["avatar"] removes the avatar. Needs MANAGE_WEBHOOKS.

Example

::webhooks ::discord::webhooks

::webhooks/modify-webhook(::webhooks/ModifyWebhookRequest({
  webhook_id: "1600000000000000000",
  channel_id: "1100000000000000001"
}))

modify-webhook-with-token

fn (request: ModifyWebhookWithTokenRequest): Map
fn (request: ModifyWebhookWithTokenRequest, opts: Map): Map

PATCH /webhooks/{webhook_id}/{webhook_token} - Rename a webhook or change its avatar using its token. Cannot move channels.

Example

::webhooks ::discord::webhooks

::webhooks/modify-webhook-with-token(::webhooks/ModifyWebhookWithTokenRequest({
  webhook_id: "1600000000000000000",
  webhook_token: ::hot::ctx/get("discord.webhook.token"),
  name: "Deploy Alerts"
}))

verify-request

fn (request: Map): Bool
fn (request: Map, public-key: Str): Bool
fn (request: Map, public-key: Str, tolerance-seconds: Int): Bool

Verify a Discord interaction (or webhook event) request: the Ed25519 signature in X-Signature-Ed25519 over X-Signature-Timestamp plus the raw body (::hot::http/raw-body), and a replay window on the timestamp (default 300 seconds; pass 0 as the third argument to disable). Returns false for missing headers, a bad signature, a stale or non-numeric timestamp, or an invalid public key.

The 1-arity form reads discord.public.key and fails when it is not set. The replay window is stricter than Discord requires: on a host whose clock is more than 5 minutes off, every request (including Discord's endpoint-verification PING) fails, so pass 0 there.

Example

on-interaction
meta {webhook: {service: "discord", path: "/interactions", method: "POST"}}
fn (request: ::hot::http/HttpRequest): ::hot::http/HttpResponse {
  // Uses discord.public.key; pass the hex key as a second argument instead
  cond {
    not(::discord::webhooks/verify-request(request)) => { ::hot::http/HttpResponse({status: 401, body: "invalid request signature"}) }
    => { ::hot::http/HttpResponse({status: 200, body: {type: 1}}) }
  }
}
Context Vars: discord.public.key

Types

CreateWebhookRequest

CreateWebhookRequest type {
    channel_id: Str,
    name: Str,
    avatar: Str?,
    reason: Str?
}

DeleteWebhookMessageRequest

DeleteWebhookMessageRequest type {
    webhook_id: Str,
    webhook_token: Str,
    message_id: Str,
    thread_id: Str?
}

DeleteWebhookRequest

DeleteWebhookRequest type {
    webhook_id: Str,
    reason: Str?
}

DeleteWebhookWithTokenRequest

DeleteWebhookWithTokenRequest type {
    webhook_id: Str,
    webhook_token: Str
}

EditWebhookMessageRequest

EditWebhookMessageRequest type {
    webhook_id: Str,
    webhook_token: Str,
    message_id: Str,
    thread_id: Str?,
    with_components: Bool?,
    content: Str?,
    embeds: Vec<Map>?,
    flags: Int?,
    allowed_mentions: Map?,
    components: Vec<Map>?,
    attachments: Vec<Map>?,
    poll: Map?,
    files: Vec<::discord::api/FileUpload>?,
    clear: Vec<Str>?
}

ExecuteWebhookRequest

ExecuteWebhookRequest type {
    webhook_id: Str,
    webhook_token: Str,
    wait: Bool?,
    thread_id: Str?,
    with_components: Bool?,
    content: Str?,
    username: Str?,
    avatar_url: Str?,
    tts: Bool?,
    embeds: Vec<Map>?,
    allowed_mentions: Map?,
    components: Vec<Map>?,
    attachments: Vec<Map>?,
    flags: Int?,
    thread_name: Str?,
    applied_tags: Vec<Str>?,
    poll: Map?,
    files: Vec<::discord::api/FileUpload>?
}

GetChannelWebhooksRequest

GetChannelWebhooksRequest type {
    channel_id: Str
}

GetGuildWebhooksRequest

GetGuildWebhooksRequest type {
    guild_id: Str
}

GetWebhookMessageRequest

GetWebhookMessageRequest type {
    webhook_id: Str,
    webhook_token: Str,
    message_id: Str,
    thread_id: Str?
}

GetWebhookRequest

GetWebhookRequest type {
    webhook_id: Str
}

GetWebhookWithTokenRequest

GetWebhookWithTokenRequest type {
    webhook_id: Str,
    webhook_token: Str
}

ModifyWebhookRequest

ModifyWebhookRequest type {
    webhook_id: Str,
    name: Str?,
    avatar: Str?,
    channel_id: Str?,
    reason: Str?,
    clear: Vec<Str>?
}

ModifyWebhookWithTokenRequest

ModifyWebhookWithTokenRequest type {
    webhook_id: Str,
    webhook_token: Str,
    name: Str?,
    avatar: Str?,
    clear: Vec<Str>?
}