discord-webhook-kit

Modern, TypeScript-first Discord Webhook client with full type safety, ESM support, and modern features.

Features

• TypeScript-first: Full type safety with comprehensive type definitions
• Modern: ESM and CJS dual build support
• Safe defaults: Prevents accidental @everyone mentions
• Rate limit handling: Automatic retry with configurable backoff
• Lightweight: Minimal dependencies (only undici)
• Simple API: Easy to use and predictable
• EmbedBuilder: Fluent API for building embeds with method chaining
• AlertClient: Pre-configured alerts for error monitoring (info/success/warn/error)

Installation

npm install discord-webhook-kit

Quick Start

import { WebhookClient } from "discord-webhook-kit";

const webhook = new WebhookClient(
  "https://discord.com/api/webhooks/YOUR_WEBHOOK_ID/YOUR_WEBHOOK_TOKEN"
);

// Send a simple message
await webhook.send("Hello, Discord!");

// Send with custom username and avatar
await webhook.send({
  content: "Hello from custom bot!",
  username: "My Bot",
  avatar_url: "https://example.com/avatar.png",
});

Usage Examples

Simple Text Message

const webhook = new WebhookClient(WEBHOOK_URL);
await webhook.send("Hello, World!");

Rich Embed Message

await webhook.send({
  content: "Check out this embed!",
  embeds: [
    {
      title: "Embed Title",
      description: "This is the embed description",
      color: 0x00ff00, // Green color
      fields: [
        { name: "Field 1", value: "Value 1", inline: true },
        { name: "Field 2", value: "Value 2", inline: true },
      ],
      footer: {
        text: "Footer text",
      },
      timestamp: new Date().toISOString(),
    },
  ],
});

Using EmbedBuilder (Method Chaining)

import { WebhookClient, EmbedBuilder } from "discord-webhook-kit";

const embed = new EmbedBuilder()
  .setTitle("My title here")
  .setAuthor(
    "Author here",
    "https://cdn.discordapp.com/embed/avatars/0.png",
    "https://www.google.com"
  )
  .setURL("https://www.google.com")
  .addField("First field", "this is inline", true)
  .addField("Second field", "this is not inline")
  .setColor("#00b0f4")
  .setThumbnail("https://cdn.discordapp.com/embed/avatars/0.png")
  .setDescription("Oh look a description :)")
  .setImage("https://cdn.discordapp.com/embed/avatars/0.png")
  .setFooter(
    "Hey its a footer",
    "https://cdn.discordapp.com/embed/avatars/0.png"
  )
  .setTimestamp();

await webhook.send({ embeds: [embed] });

With Default Options

const webhook = new WebhookClient(WEBHOOK_URL, {
  username: "Notification Bot",
  avatarUrl: "https://example.com/bot-avatar.png",
  retryOnRateLimit: true,
  maxRetries: 5,
  timeout: 10000,
});

// All messages will use the default username and avatar
await webhook.send("This uses default settings!");

Send to Thread

const webhook = new WebhookClient(WEBHOOK_URL, {
  threadId: "1234567890",
});

await webhook.send("Message sent to a specific thread!");

Disable Rate Limit Retry

const webhook = new WebhookClient(WEBHOOK_URL, {
  retryOnRateLimit: false,
});

try {
  await webhook.send("Message");
} catch (error) {
  if (error instanceof DiscordWebhookError && error.isRateLimit()) {
    console.log("Rate limited! Try again later.");
  }
}

API Reference

WebhookClient

new WebhookClient(webhookUrl: string, options?: WebhookClientOptions)

Constructor Options

Option	Type	Default	Description
username	string	-	Default username for all messages
avatarUrl	string	-	Default avatar URL for all messages
wait	boolean	true	Wait for server confirmation
threadId	string	-	Thread ID to send messages to
retryOnRateLimit	boolean	true	Automatically retry on rate limit
maxRetries	number	3	Maximum retry attempts on rate limit
timeout	number	30000	Request timeout in milliseconds

Methods

send(content: string | WebhookMessage): Promise<WebhookResponse>

Sends a message to the Discord webhook.

// String shorthand
await webhook.send("Hello!");

// Full message object
await webhook.send({
  content: "Hello!",
  username: "Custom Name",
  embeds: [{ title: "Embed" }],
});

getMaskedUrl(): string

Returns a masked version of the webhook URL safe for logging.

console.log(webhook.getMaskedUrl());
// Output: /webhooks/1234567890/abcd...wxyz

WebhookMessage

Field	Type	Description
content	string	Message content (max 2000 chars)
username	string	Override webhook username
avatar_url	string	Override webhook avatar
tts	boolean	Text-to-speech message
embeds	WebhookEmbed[]	Array of embeds (max 10)
allowed_mentions	AllowedMentions	Mention control
flags	number	Message flags
thread_name	string	Thread name (for forum channels)
applied_tags	string[]	Tag IDs (for forum channels)

WebhookEmbed

Field	Type	Description
title	string	Embed title (max 256 chars)
description	string	Embed description (max 4096)
url	string	URL for title link
color	number	Color code (decimal)
timestamp	string	ISO8601 timestamp
footer	WebhookEmbedFooter	Footer object
image	WebhookEmbedMedia	Image object
thumbnail	WebhookEmbedMedia	Thumbnail object
author	WebhookEmbedAuthor	Author object
fields	WebhookEmbedField[]	Fields array (max 25)

EmbedBuilder

Builder class for creating embeds with method chaining.

Method	Description
setTitle(title)	Set embed title
setDescription(description)	Set embed description
setURL(url)	Set embed URL
setColor(color)	Set color (hex string or number)
setAuthor(name, iconUrl?, url?)	Set author info
setThumbnail(url)	Set thumbnail image
setImage(url)	Set main image
setFooter(text, iconUrl?)	Set footer
setTimestamp(timestamp?)	Set timestamp (default: now)
addField(name, value, inline?)	Add a field
addFields(...fields)	Add multiple fields
toJSON()	Convert to plain embed object

DiscordWebhookError

Custom error class for Discord API errors.

try {
  await webhook.send("Message");
} catch (error) {
  if (error instanceof DiscordWebhookError) {
    console.log("Status:", error.status);
    console.log("Message:", error.message);
    console.log("Raw body:", error.rawBody);
    console.log("Request ID:", error.requestId);
    console.log("Is rate limit:", error.isRateLimit());
  }
}

AlertClient (Error Alerting)

AlertClient provides a convenient way to send formatted alerts to Discord, perfect for error monitoring and application notifications.

import { AlertClient } from "discord-webhook-kit";

const alert = new AlertClient(WEBHOOK_URL, {
  appName: "My API",
  environment: "production",
  username: "Alert Bot",
  avatarUrl: "https://example.com/avatar.png",
});

// Info alert (blue)
await alert.info("User logged in", {
  fields: [{ name: "User ID", value: "12345" }],
});

// Success alert (green)
await alert.success("Payment completed", {
  fields: [
    { name: "Amount", value: "$100.00" },
    { name: "Order ID", value: "ORD-123" },
  ],
});

// Warning alert (yellow)
await alert.warn("High memory usage detected", {
  fields: [{ name: "Usage", value: "85%" }],
});

// Error alert (red) - with Error object auto-formatting
try {
  await riskyOperation();
} catch (err) {
  await alert.error(err); // Auto-formats Error with stack trace
}

// Error alert with custom message and error
await alert.error("Database operation failed", {
  error: caughtError,
  fields: [{ name: "Query", value: "SELECT * FROM users" }],
});

AlertClient Options

Option	Type	Default	Description
appName	string	"Alert"	Application name shown in title
environment	string	-	Environment (e.g., "production")
username	string	-	Default webhook username
avatarUrl	string	-	Default webhook avatar

Alert Colors

Level	Color	Hex Code
info	Blue	#3498db
success	Green	#00ff1d
warn	Yellow	#f1c40f
error	Red	#ff0000

Error Auto-Formatting

When passing an Error object to alert.error(), it automatically:

• Extracts error name and message
• Includes code and status properties if present
• Formats stack trace in a code block
• Respects Discord's field limits (auto-trims long content)

Safe Defaults

By default, discord-webhook-kit disables @everyone and @here mentions to prevent accidental mass pings:

// Default: allowed_mentions is set to { parse: [] }
await webhook.send("@everyone Hello!"); // Won't ping everyone

// To enable mentions, explicitly set allowed_mentions
await webhook.send({
  content: "@everyone Hello!",
  allowed_mentions: { parse: ["everyone"] },
});

Requirements

• Node.js 18.0.0 or higher

Related

• Discord.js Documentation - Official Discord.js docs
• Discord Webhook API - Official Discord API documentation

License

MIT