@eliware/discord-webhook

A simple, promise-based Discord webhook sender for Node.js with built-in rate limit handling.

Table of Contents

• Features
• Installation
• Usage
• API
• TypeScript
• License

Features

• Send messages to Discord webhooks with a single function
• Handles Discord rate limits automatically (HTTP 429)
• ESM-first, TypeScript types included
• Customizable fetch for testing/mocking
• Supports default webhook URL from process.env.DISCORD_WEBHOOK

Installation

npm install @eliware/discord-webhook

Usage

ESM Example

import { sendMessage } from '@eliware/discord-webhook';

const webhookUrl = 'https://discord.com/api/webhooks/your-webhook-id/your-webhook-token';
const messageBody = { content: 'Hello from discord-webhook!' };

(async () => {
  try {
    const response = await sendMessage({ url: webhookUrl, body: messageBody });
    if (response.ok) {
      console.log('Message sent successfully!');
    } else {
      console.error('Failed to send message:', response.status, await response.text());
    }
  } catch (err) {
    console.error('Error sending message:', err);
  }
})();

API

sendMessage({ body, url = process.env.DISCORD_WEBHOOK, maxRetries = 3, fetchFn = fetch })

Sends a message to a Discord webhook URL, handling rate limits with automatic retry.

Parameters:

• body (object): The JSON body to send (e.g., { content: 'Hello!' }).
• url (string, optional): The Discord webhook URL. Defaults to process.env.DISCORD_WEBHOOK.
• maxRetries (number, optional): Maximum number of retries on rate limit (default: 3).
• fetchFn (function, optional): Custom fetch function for testing/mocking (default: fetch).

Returns:

• Promise<Response>: The fetch response.

Throws:

• Error if the URL or body is invalid, or if max retries are exceeded due to rate limiting.

TypeScript

Type definitions are included:

export declare function sendMessage(params?: {
  body: object;
  url?: string;
  maxRetries?: number;
  fetchFn?: typeof fetch;
}): Promise<Response>;

Support

For help, questions, or to chat with the author and community, visit:

eliware.org on Discord

License

MIT © 2025 Eli Sterling, eliware.org

Links

• Home Page
• GitHub
• npm
• Discord