Faizo

Writing · Discord API · Webhooks · Rust

Discord keeps your webhook's avatar_url, not the image, so host it forever

Discord stores your webhook's avatar_url, not the image. Why uploaded avatars break later, the silent size limits, and how to host them permanently.

When you execute a Discord webhook you can override how the message looks: username sets the display name and avatar_url sets the picture. It feels like an upload. It isn't. Discord stores the URL string with the message and loads the image through its media proxy when the message is displayed. If the URL stops serving an image, every message that used it loses its avatar, and there is no way to point an existing message at a new picture: editing a webhook message can change its content, but not its username or avatar.

In DWEEB people kept asking to upload an avatar from their computer rather than paste a link. This is what I learned building that, including two "cheap" designs that don't work.

Two ideas that don't work

A short-lived image store

The first idea was to accept the upload, keep it for a day or so, and let Discord fetch it once. That works for exactly as long as Discord's media cache holds the image. After that, a message that is supposed to be permanent (a server's rules, a role menu, an announcement) shows a broken avatar. Since the URL is what's stored, the lifetime of the hosting is the lifetime of the avatar.

Discord's own attachment CDN

The clever idea was to post the image as an attachment in a throwaway webhook message, keep the cdn.discordapp.com/attachments/… link Discord returns, and delete the message. Discord would host the image for free. Unfortunately Discord rejects its own attachment URLs in avatar_url, both with and without the signed ?ex=&is=&hm= query parameters attachment links now carry. This is a known limitation (discussed in the discord-api-docs issue tracker, #6657), not a bug in your request. Don't spend an afternoon on it.

The limits Discord doesn't tell you about

Two more things fail silently, with no error from the API:

  • Large images. Above roughly 1024 pixels on a side, Discord quietly shows the default webhook avatar instead of yours. The request succeeds and the message posts normally.
  • Animated GIFs. A webhook avatar doesn't animate. You get a still frame at best.

Silent failures are the worst kind for a tool whose whole job is "what you see is what gets posted", so the fix had to make sure no oversized or animated image ever reached Discord.

The design: the browser does the pixels, the server just keeps them

In the browser

Image processing is cheap in the browser and expensive on a small server, so all of it happens client-side. The uploaded image is center-cropped to a square (Discord shows avatars in a circle, so a square source loses the least), scaled down to 256×256, and re-encoded:

async function prepareAvatar(file) {
  const bitmap = await createImageBitmap(file); // first frame only for GIFs
  const side = Math.min(bitmap.width, bitmap.height);
  const size = Math.min(256, side);
  const canvas = new OffscreenCanvas(size, size);
  const ctx = canvas.getContext("2d");
  ctx.drawImage(
    bitmap,
    (bitmap.width - side) / 2, (bitmap.height - side) / 2, side, side,
    0, 0, size, size,
  );
  const png = await canvas.convertToBlob({ type: "image/png" });
  if (hasTransparency(ctx, size) || png.size <= PNG_SIZE_BUDGET) return png;
  return canvas.convertToBlob({ type: "image/jpeg", quality: 0.9 });
}

The format choice matters more than it looks. If the image has any transparent pixels it stays PNG, because JPEG has no alpha channel and transparent areas turn black, which looks awful inside Discord's circular crop. Opaque images stay PNG while they're small and switch to JPEG beyond a size budget.

On the server

The server never decodes an image. It reads the header bytes of the format it was given to check the type and dimensions, and refuses anything else. For PNG that is a fixed position in the file:

fn png_dimensions(bytes: &[u8]) -> Option<(u32, u32)> {
    const SIGNATURE: &[u8] = b"\x89PNG\r\n\x1a\n";
    // 8-byte signature, then the IHDR chunk: length(4) "IHDR"(4) width(4) height(4)
    if bytes.len() < 24 || &bytes[..8] != SIGNATURE || &bytes[12..16] != b"IHDR" {
        return None;
    }
    let width = u32::from_be_bytes(bytes[16..20].try_into().ok()?);
    let height = u32::from_be_bytes(bytes[20..24].try_into().ok()?);
    Some((width, height))
}

JPEG takes a little more work (walk the segments to the first start-of-frame marker), but it's still a few dozen lines with no image library. That keeps the server's dependency list and attack surface small, and the browser has already done the actual resizing.

Storage that never forgets

  • Content-addressed. The file is stored and served under its SHA-256 hash, as /api/avatar/<sha256>.png. The same image uploaded twice is stored once.
  • Immutable. Since the URL names the exact bytes, it is served with a one-year immutable cache header. Discord's media proxy, browsers and CDNs can all cache it forever.
  • Anonymous reads. Discord's fetcher carries no credentials, so serving is public. Uploading is not: only signed-in users can upload, so the endpoint can't become a free image host.
  • Never swept. There is no garbage collector. Deleting a row would silently break a live message somewhere, and I can't know which messages still exist. Growth is bounded by deduplication, a per-file size cap and a total row cap. When the cap is reached, uploads get a "try again later" error. Old images are never evicted to make room.

Keep the field a URL

One last decision: the upload doesn't replace the avatar URL field, it fills it in. People still paste existing CDN links, and DWEEB supports placeholders like {server_icon} that resolve to the server's icon at send time. An upload is just a convenient way to get a URL that will last.

Summary

  • avatar_url stores a link. Whatever hosts it must outlive every message that uses it.
  • Discord's own attachment links aren't accepted as avatars.
  • Stay at or below 1024×1024 and don't count on animation. 256×256 is plenty.
  • Preserve transparency with PNG. Discord crops avatars to a circle.
  • Content-address, cache immutably, and never delete.

The same rule applies to any image URL you put into a Discord message that is meant to last, including embed thumbnails and Components V2 media. If you're linking to it rather than uploading it as an attachment, you are now its host.