Webhook embeds

Messages posted through this lane are not end-to-end encrypted, and they are not posted as your bot.A webhook message is written to the server’s database as readable text by design. The server, and anyone with server-side access, can read it. It is attributed to a webhook identity with its own name and avatar, and shipped Cloak clients render it with a webhook badge carrying a “not encrypted” notice. Nothing about this is recoverable after the fact.The payload type is called UnencryptedWebhookPost, and unencrypted: true is required on every post. That is deliberate: the trade should be impossible to make by accident.

For most bots the answer is rich cards instead. client.sendCard() is encrypted, posts under your bot’s own identity, needs only message_send, and has no quota. Read this page only if you need something the card lane cannot do.

What you give up

The message is plaintext on the server. client.send() and client.sendCard() encrypt in your process and Cloak stores ciphertext. A webhook post is stored as text.
It is not posted as your bot. It carries the webhook’s name and avatar, plus the “not encrypted” badge.
Your bot will not see it come back. Webhook messages arrive as a systemMessage with type: 'unknown', never as messageCreate. That conveniently avoids an echo loop, and it also means you cannot read your own embeds back.

When this lane is still the right choice

Three things only the webhook lane can do:

Many personas from one identity. Set username and avatar_url per post. One webhook can speak as your CI, your alerting, and your changelog.
Posting with no bot account at all. A human creates the webhook in the Cloak app, you put the URL in an environment variable, and anything that can make an HTTPS request can post.
Reaching clients older than the card rollout. Those clients render a card’s message as its plain content text. A webhook embed renders everywhere.

If the content is sensitive, use sendCard() or send() instead.

The recommended path, with no manage_server

Have a human create the webhook in the Cloak app under Room settings > Webhooks, hand your bot the URL in an environment variable, and post to it. The bot needs no permissions at all for the post itself: no manage_server, no CRUD calls, no rate limit of its own, and no way to rotate a token somebody else’s integration depends on. Most bots should not hold manage_server.

await client.webhooks.post(process.env.CLOAK_WEBHOOK_URL!, {
  unencrypted: true, // required: this message is NOT end-to-end encrypted
  username: 'Deploy Bot', // per-post display-name override, 1 to 80 characters
  embeds: [
    {
      title: 'Build #421 passed',
      url: 'https://ci.example.com/builds/421',
      description: 'All 490 tests green on `main`.',
      color: '#22c55e', // a CSS color string or a decimal int
      fields: [
        { name: 'Duration', value: '1m 42s', inline: true },
        { name: 'Commit', value: '`7d4e022`', inline: true },
      ],
      footer: { text: 'ci.example.com' },
      timestamp: new Date().toISOString(),
    },
  ],
});

unencrypted: true is re-checked at runtime, not just by the type, so a plain JavaScript caller cannot skip it. The key never reaches the wire, it is an acknowledgement to the SDK.

The delivery URL is a bearer credential. It embeds the webhook’s token secret, the server stores only a hash of it, and it is returned exactly once. webhooks.list() cannot get it back.Never commit it, never log it, never write it to your keystore. The SDK holds up its end: the URL never appears in an error message, an event, or a log line, and CloakWebhookError carries only the non-secret webhookId.

Minting one yourself, which needs manage_server

sendEmbed() finds or mints a webhook for the channel and posts through it:

await client.sendEmbed(serverId, channelId, {
  unencrypted: true,
  embeds: [{ title: 'Deployed', description: 'v1.4.0 is live.' }],
});

On a cold start it lists the server’s webhooks and looks for one in that channel that the bot itself created, then rotates that webhook’s token to obtain a usable URL. Listing never returns a token, so there is no other way to get one. A webhook a human created is never adopted, because rotating it would silently break whatever was already posting to it. Only when there is no match does the SDK mint a new webhook, named after ClientOptions.webhookName (default 'Bot'). That reuse path is load-bearing rather than an optimization. Creations are capped at 10 per account per hour and 15 per channel, so a restart loop that minted every time would exhaust the quota. A bot posting to N channels mints N webhooks. The minted URL is cached in memory only and never persisted. If someone rotates or deletes the webhook out from under you, the next post gets a 401, and sendEmbed() re-mints and retries exactly once.

The CRUD surface

Every method below requires manage_server, except post() which requires nothing. All of them are also pre-bound on the server handle as client.guild(serverId).webhooks, with the serverId argument dropped.

Method	Notes
`webhooks.list(serverId)`	Returns `WebhookInfo[]`. Never includes a token.
`webhooks.create(serverId, channelId, name, opts?)`	Returns the one-time `{ id, url }`. `opts.icon` and `opts.miniIcon` are already-hosted image URLs, the SDK never uploads.
`webhooks.edit(serverId, webhookId, changes)`	Rename, re-icon, or move channels. `icon` and `miniIcon` are written as a pair.
`webhooks.regenerate(serverId, webhookId)`	Returns a fresh `{ id, url }` and permanently kills the previous URL.
`webhooks.delete(serverId, webhookId)`	Messages it already posted keep rendering.
`webhooks.post(url, post)`	The delivery POST. No permission required.

A denial on a CRUD call rejects with CloakActionError, carrying the permission that was missing. A failed delivery POST rejects with CloakWebhookError. See handling errors.

Two server settings decide whether any of this works

Both live on the Cloak server, not in your bot, and you cannot detect either from the SDK.

WEBHOOK_INGRESS_PORT and WEBHOOK_PUBLIC_BASE

The webhook ingress does not run at all unless the port is set. WEBHOOK_PUBLIC_BASE defaults to an empty string, which makes the server hand back a relative /webhooks/{id}/{secret} path instead of an absolute URL.The SDK refuses to post to a non-absolute URL and names both variables in the error. It also refuses plain http:// to anything but localhost, 127.0.0.1 or ::1, because the token secret is a path component of the URL and would travel in cleartext.

IMGPROXY_SECRET and IMGPROXY_PUBLIC_BASE

Without them, every embed image and icon is silently dropped.Each URL a viewer would auto-fetch (image.url, thumbnail.url, video.url, author.icon_url, footer.icon_url, provider.icon, and a per-post avatar_url) is rewritten through the server’s signed image proxy so viewers never hit a third-party origin. When the proxy is unconfigured, or the URL is not plain http(s), the field is stripped and the POST still returns success. There is no error, no warning, and no way to tell from the response.Text and click-through links always survive: title, description, url, color, timestamp, fields, author.name, provider.name and footer.text.Quick check on a live deployment: set avatar_url on a post. If the avatar does not change, the proxy is off and your image will vanish too.

Caps

The server normalizes leniently. Out-of-spec payloads are truncated rather than rejected, except for the four hard 400s.

Limit	Value	Behavior
`content`	2000 characters	Hard `400`, pre-checked by the SDK
Serialized `embeds`	6000 bytes, measured after the proxy rewrite	Hard `400 embeds too large`
Request body	64 KiB	Hard `400`
Empty post, no content and no embeds	Refused outright	Hard `400 empty`, pre-checked by the SDK
Embeds per post	First 10 kept	Truncated
`title`, `description`	256, 4096	Truncated
`author.name`, `footer.text`	256, 2048	Truncated
`fields`	First 25 kept, `name` 256, `value` 1024	Truncated
`username` override	1 to 80 characters	Out-of-range falls back to the webhook’s stored name
Posting rate	30 per webhook and 120 per source IP, per 60 seconds	`429`
Webhook creation	10 per account per hour, 15 per channel	Denied on create

A proxied URL is longer than the original, and the 6000-byte embed budget is measured after the rewrite, so your real budget is smaller than 6000. The SDK deliberately does not pre-check it, because any client-side number would be wrong. The server answers 400 embeds too large instead. Two shape differences from Discord: color accepts either a decimal int or a CSS color string, and fields[].inline defaults to true here rather than false. Pass inline explicitly if you care.

Errors

CloakWebhookError is the delivery failure, raised by webhooks.post() and sendEmbed().

This lane reports failures differently from the encrypted one. client.send() and client.sendCard() are fire-and-forget: a server-side denial arrives later on the sendRejected event rather than rejecting the promise. A webhook post is an ordinary HTTPS request, so a failure rejects, and only a 204 counts as success.

import { CloakWebhookError } from '@cloak-software/bot-sdk';

try {
  await client.webhooks.post(url, { unencrypted: true, content: 'hello' });
} catch (e) {
  if (e instanceof CloakWebhookError) {
    // e.status: HTTP status, or 0 for a transport or pre-check failure
    // e.detail: 'content' | 'embeds' | 'embeds too large' | 'empty' |
    //           'unauthorized' | 'rate limited' | 'delivery failed' |
    //           'transport' | 'precheck'
    // e.webhookId: the non-secret id, when known. Never the URL.
    console.error(`webhook post failed: ${e.status} ${e.detail}`);
    return;
  }
  throw e;
}

Status	What happened
`0`	Pre-check, network, TLS, or the SDK’s 15 second POST timeout
`400`	The payload was refused. `embeds too large` means it exceeded 6000 bytes after the proxy rewrite
`401`	The token was regenerated (which permanently kills the previous URL) or the webhook was deleted
`404`	The ingress is not running that route, or `WEBHOOK_PUBLIC_BASE` points somewhere else
`429`	Rate limited, 30 posts per webhook and 120 per source IP per 60 seconds
`500`	Delivery failed server-side

A complete webhook embed bot

import { Client, CloakWebhookError } from '@cloak-software/bot-sdk';

const webhookUrl = process.env.CLOAK_WEBHOOK_URL!;

const client = new Client({
  token: process.env.CLOAK_TOKEN!,
  // Without a keystore this bot works once and is bricked on its second run.
  // See /concepts/keys-and-keystore.
  keystorePath: './embed-bot.cloak-keystore.json',
  // No manage_server: this bot only posts to a human-created webhook URL.
  requiredPermissions: ['view_text', 'message_send'],
});

client.on('messageCreate', async (msg) => {
  if (msg.authorId === client.user?.id) return; // ignore our own messages
  // Webhooks are server-scoped, and a DM has a null serverId.
  if (msg.isDM || !msg.serverId) return;
  if (msg.content.trim() !== '!deploy') return;

  try {
    await client.webhooks.post(webhookUrl, {
      unencrypted: true, // required: this message is NOT end-to-end encrypted
      username: 'Deploy Bot',
      embeds: [
        {
          title: 'v1.4.0 is live',
          description: 'Deployed to production from `main`.',
          color: '#22c55e',
          url: 'https://ci.example.com/builds/421',
          timestamp: new Date().toISOString(),
        },
      ],
    });
    // The bot never receives this post back, so acknowledge in the encrypted
    // lane if the channel should see one.
    await msg.channel.send('Posted the deploy notice.');
  } catch (e) {
    if (e instanceof CloakWebhookError) {
      console.error(`webhook post failed: ${e.status} ${e.detail}`);
      return;
    }
    throw e;
  }
});

client.on('error', (e) => console.error('sdk error', e));

client.login().catch((e) => {
  console.error('login failed', e);
  process.exit(1);
});

The SDK ships this as a runnable example that also covers minting and listing. Run it with npm run example:embed.

Webhooks reference

Every method, type, constant and error on this lane.

Rich cards

The encrypted lane, posted under your bot’s own identity.

Handling errors

Which failures throw, which arrive as events.

Permissions

What manage_server covers, and what it does not.

Get started

Core concepts

Messaging

Slash commands

Embeds and cards

Voice

Server management

Advanced

Running in production

Examples

API reference

Reference

What you give up

When this lane is still the right choice

The recommended path, with no manage_server

Minting one yourself, which needs manage_server

The CRUD surface

Two server settings decide whether any of this works

Caps

Errors

A complete webhook embed bot

Next

Webhooks reference

Rich cards

Handling errors

Permissions

​What you give up

​When this lane is still the right choice

​The recommended path, with no manage_server

​Minting one yourself, which needs manage_server

​The CRUD surface

​Two server settings decide whether any of this works

​Caps

​Errors

​A complete webhook embed bot

​Next

Webhooks reference

Rich cards

Handling errors

Permissions

What you give up

When this lane is still the right choice

The recommended path, with no manage_server

Minting one yourself, which needs manage_server

The CRUD surface

Two server settings decide whether any of this works

Caps

Errors

A complete webhook embed bot

Next