Webhooks

Webhooks are a powerful way to send messages to Discord channels without requiring a bot to be online. They’re perfect for external integrations, custom message appearances, and sending multiple embeds in one message.

Available since v4.15.0

Webhooks are built into DiSky v4.15.0+. Previous versions required a separate module.

What Are Webhooks?

Webhooks are special URLs that let you send messages to a specific Discord channel. Unlike bot messages, webhook messages can:

• Use custom usernames and avatars per message
• Send up to 5 embeds in a single message (bots can only send 1)
• Work without a bot being online
• Appear to come from different “users”

There are two types of webhooks in DiSky:

• Webhook Clients - Registered webhooks you can use to send messages
• Normal Webhooks - Webhooks retrieved from channels (read-only information)

Creating a Webhook in Discord

Before using webhooks in DiSky, create one in Discord:

1. Open Channel Settings

   Right-click the target channel and select “Edit Channel”

2. Go to Integrations

   Navigate to the “Integrations” tab in the settings

3. Create Webhook

   Click “Create Webhook” or “New Webhook”

4. Configure Webhook (Optional)

   Set the default name and avatar (you can override these in code)

5. Copy Webhook URL

   Click “Copy Webhook URL” - you’ll need this for DiSky

The webhook URL looks like:

https://discord.com/api/webhooks/123456789012345678/AbCdEfGhIjKlMnOpQrStUvWxYz

Keep URLs Secret

Webhook URLs are sensitive! Anyone with the URL can send messages to the channel. Never share them publicly or commit them to version control.

Registering a Webhook Client

Register your webhook in DiSky to use it for sending messages:

Basic Registration

on ready:
    # Register with a name you'll use in code
    register webhooks using event-bot named "announcements" with url "https://discord.com/api/webhooks/..."

Where to Register

Register webhooks in the on ready section of your bot. This ensures they’re registered once when the bot starts, not every time you use them.

Multiple Webhooks

on ready:
    # Register multiple webhooks for different purposes
    register webhooks using event-bot named "announcements" with url "https://discord.com/api/webhooks/..."
    register webhooks using event-bot named "logs" with url "https://discord.com/api/webhooks/..."
    register webhooks using event-bot named "alerts" with url "https://discord.com/api/webhooks/..."

The name is your identifier in code - it’s not sent to Discord.

Sending Messages with Webhooks

Once registered, use the webhook client to send messages:

Basic Message

command /announce <text>:
    trigger:
        # Send simple text message
        make client "announcements" post arg-1

Custom Username and Avatar

command /say <text>:
    trigger:
        make client "announcements" post arg-1 with username "Custom Bot" with avatar url "https://example.com/avatar.png"

Rich Message with Embeds

command /news <text>:
    trigger:
        create a new message and store it in {_msg}:
            set the content of the message to "📰 **Breaking News**"

            make embed:
                set title of embed to "News Update"
                set description of embed to arg-1
                set embed color of embed to blue
                set timestamp of embed to now
            add last embed to the embeds of the message

        make client "announcements" post {_msg} with username "News Bot" with avatar url "https://example.com/news-icon.png"

Multiple Embeds (Webhook-Only Feature!)

command /multi-embed:
    trigger:
        create a new message and store it in {_msg}:
            set the content of the message to "Multiple embeds in one message!"

            # First embed
            make embed:
                set title of embed to "First Embed"
                set description of embed to "This is the first embed"
                set embed color of embed to red
            add last embed to the embeds of the message

            # Second embed
            make embed:
                set title of embed to "Second Embed"
                set description of embed to "This is the second embed"
                set embed color of embed to blue
            add last embed to the embeds of the message

            # Third embed
            make embed:
                set title of embed to "Third Embed"
                set description of embed to "This is the third embed"
                set embed color of embed to green
            add last embed to the embeds of the message

        make client "announcements" post {_msg} with username "Multi-Embed Bot"

Webhook Advantage

Only webhooks can send up to 5 embeds per message. Bots are limited to just 1 embed per message!

Storing the Sent Message

You can capture the sent message for later use:

make client "announcements" post "Hello!" and store it in {_sentMessage}

# Now you can work with the message
set {_id} to discord id of {_sentMessage}
broadcast "Message ID: %{_id}%"

Managing Webhooks

Retrieving Webhooks

Get webhooks from channels or guilds:

By Channel

command /listwebhooks:
    trigger:
        retrieve webhooks of event-channel and store them in {_webhooks::*}

        if size of {_webhooks::*} is 0:
            reply with "No webhooks found in this channel."
        else:
            reply with "Found %size of {_webhooks::*}% webhooks."

By Guild

command /guildwebhooks:
    trigger:
        retrieve webhooks of event-guild and store them in {_webhooks::*}

        set {_list::*} to "%size of {_webhooks::*}% webhooks found:"
        loop {_webhooks::*}:
            set {_name} to discord name of loop-value
            set {_id} to discord id of loop-value
            set {_channel} to text channel of loop-value
            add "- %{_name}% (%{_id}%) in %mention tag of {_channel}%" to {_list::*}

        reply with join {_list::*} with nl

Webhook Properties

Retrieved webhooks provide information:

retrieve webhooks of event-guild and store them in {_webhooks::*}

loop {_webhooks::*}:
    set {_webhook} to loop-value

    # Get properties
    set {_name} to discord name of {_webhook}
    set {_id} to discord id of {_webhook}
    set {_channel} to text channel of {_webhook}
    set {_guild} to guild of {_webhook}
    set {_created} to creation date of {_webhook}

    broadcast "Webhook: %{_name}% (ID: %{_id}%)"

Deleting Webhooks

command /deletewebhook <text>:
    trigger:
        retrieve webhooks of event-channel and store them in {_webhooks::*}

        loop {_webhooks::*}:
            if discord name of loop-value is arg-1:
                delete loop-value
                reply with "✅ Deleted webhook: %arg-1%"
                stop

        reply with "❌ Webhook not found: %arg-1%"

Practical Examples

Server Status Updates

on script load:
    register webhooks using bot named "my-bot" named "status" with url "https://discord.com/api/webhooks/..."

every 5 minutes:
    set {_status} to "Online"  # Get real status
    set {_players} to number of all players

    create a new message and store it in {_msg}:
        make embed:
            set title of embed to "Server Status"
            add inline field named "Status" with value {_status} to fields of embed
            add inline field named "Players" with value "%{_players}%/100" to fields of embed
            set embed color of embed to green
            set timestamp of embed to now
        add last embed to the embeds of the message

    make client "status" post {_msg} with username "Server Monitor"

GitHub-Style Commits

command /commit <text>:
    trigger:
        create a new message and store it in {_msg}:
            make embed:
                set author of embed to event-user's name
                set author icon of embed to avatar of event-user
                set title of embed to "New Commit"
                set description of embed to "```%arg-1%```"
                set embed color of embed to hex "#6e5494"
                set timestamp of embed to now
            add last embed to the embeds of the message

        make client "logs" post {_msg} with username "GitHub" with avatar url "https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png"

Cross-Server Announcements

command /announce-all <text>:
    trigger:
        set {_announcement} to arg-1

        create a new message and store it in {_msg}:
            make embed:
                set title of embed to "📢 Network Announcement"
                set description of embed to {_announcement}
                set embed color of embed to orange
                set footer of embed to "Sent from %event-guild's name%"
            add last embed to the embeds of the message

        # Send to multiple webhooks across servers
        make client "server1-announcements" post {_msg} with username "Network Admin"
        make client "server2-announcements" post {_msg} with username "Network Admin"
        make client "server3-announcements" post {_msg} with username "Network Admin"

        reply with "✅ Announcement sent to all servers!"

Minecraft Chat Bridge

on chat:
    # Format the message
    set {_username} to player's name
    set {_message} to message

    # Send to Discord via webhook
    make client "chat-bridge" post "**%{_username}%:** %{_message}%" with username "Minecraft" with avatar url "https://crafatar.com/avatars/%player's uuid%"

# Optionally, mirror Discord messages to Minecraft
# This would require Discord bot events (not webhook)

Custom Notification System

function notify(title: text, message: text, color: text, webhook: text):
    create a new message and store it in {_msg}:
        make embed:
            set title of embed to {_title}
            set description of embed to {_message}
            set embed color of embed to {_color}
            set timestamp of embed to now
        add last embed to the embeds of the message

    make client {_webhook} post {_msg} with username "Notification Bot"

# Usage
on player join:
    notify("Player Joined", "%player% joined the server", "green", "events")

on player quit:
    notify("Player Left", "%player% left the server", "red", "events")

External Service Integration

# Example: Stripe payment notifications
function stripeWebhook(event: text, amount: text, customer: text):
    create a new message and store it in {_msg}:
        make embed:
            set title of embed to "💳 Payment Received"
            add field named "Event" with value {_event} to fields of embed
            add field named "Amount" with value "$%{_amount}%" to fields of embed
            add field named "Customer" with value {_customer} to fields of embed
            set embed color of embed to hex "#6772e5"
            set timestamp of embed to now
        add last embed to the embeds of the message

    make client "payments" post {_msg} with username "Stripe" with avatar url "https://stripe.com/img/favicon.ico"

Multi-Embed Statistics

command /stats:
    trigger:
        create a new message and store it in {_msg}:
            # Server stats embed
            make embed:
                set title of embed to "🖥️ Server Statistics"
                add inline field named "TPS" with value "20.0" to fields of embed
                add inline field named "RAM" with value "2.5 GB / 8 GB" to fields of embed
                add inline field named "Uptime" with value "7 days" to fields of embed
                set embed color of embed to green
            add last embed to the embeds of the message

            # Player stats embed
            make embed:
                set title of embed to "👥 Player Statistics"
                add inline field named "Online" with value "42" to fields of embed
                add inline field named "Total" with value "1,234" to fields of embed
                add inline field named "New Today" with value "7" to fields of embed
                set embed color of embed to blue
            add last embed to the embeds of the message

            # Economy stats embed
            make embed:
                set title of embed to "💰 Economy Statistics"
                add inline field named "Total Money" with value "$1,000,000" to fields of embed
                add inline field named "Average Balance" with value "$850" to fields of embed
                add inline field named "Richest Player" with value "Steve ($50,000)" to fields of embed
                set embed color of embed to gold
            add last embed to the embeds of the message

        make client "stats" post {_msg} with username "Statistics Bot"

Best Practices

1. Keep URLs Secret

   Store webhook URLs in configuration files, not in scripts. Never commit them to public repositories.

2. Use Descriptive Names

   Name your webhook clients clearly: "announcements", "logs", "alerts", etc.

3. Customize Appearance

   Use different usernames and avatars for different types of messages to make them easily distinguishable.

4. Rate Limit Awareness

   Webhooks share Discord’s rate limits. Don’t spam messages - space them out.

5. Error Handling

   Wrap webhook operations in try/catch blocks to handle deleted or invalid webhooks gracefully.

6. Clean Up Old Webhooks

   Periodically review and delete unused webhooks to keep channels organized.

Webhook vs Bot Messages

Feature	Bot Messages	Webhook Messages
Requires bot online	✅ Yes	❌ No
Custom username per message	❌ No	✅ Yes
Custom avatar per message	❌ No	✅ Yes
Embeds per message	1	Up to 5
Can edit messages	✅ Yes	✅ Yes (if stored)
Can delete messages	✅ Yes	✅ Yes (if stored)
Can use components	✅ Yes	❌ No
Shows bot tag	✅ Yes	❌ No (shows “BOT”)

Troubleshooting

”Unknown Webhook” Error

Problem: Webhook not found or deleted.

Solutions:

• Verify the webhook URL is correct
• Check if the webhook was deleted in Discord
• Re-create the webhook and update the URL
• Use try/catch to handle missing webhooks gracefully

Messages Not Sending

Problem: Webhook messages don’t appear.

Solutions:

• Verify webhook registration ran (check bot loaded)
• Ensure the webhook URL is complete and correct
• Check for error messages in console
• Verify the channel still exists

Rate Limited

Problem: “You are being rate limited” error.

Solutions:

• Reduce message frequency
• Space out webhook posts
• Use different webhooks for different purposes
• Implement delays between messages

Avatar Not Showing

Problem: Custom avatar doesn’t display.

Solutions:

• Verify the avatar URL is valid and accessible
• Use direct image links (PNG, JPG, GIF)
• Ensure the URL uses HTTPS
• Check if the image is within size limits

Security Considerations

1. Never Share Webhook URLs - Treat them like passwords
2. Use Environment Variables - Store URLs in config files, not code
3. Regenerate if Exposed - If a webhook URL leaks, delete it and create a new one
4. Limit Permissions - Only give webhook access to trusted systems
5. Monitor Usage - Watch for unauthorized webhook usage

Next Steps

• Learn about Simple Messages
• Create Advanced Messages
• Upload Files with webhooks
• Add Emojis to webhook messages