BotGhost Documentation
Support ServerYouTubeMarketplaceBotGhost PremiumSign in
  • Welcome to BotGhost
  • Guidelines & Privacy
  • Changelogs 2025
    • Changelogs 2024
    • Changelogs 2023
  • BotPanel Documentation
  • Getting Started
    • Create Your First Bot
      • Create Your Second Bot
    • Invite Your Bot
    • Standard Practices
      • Advanced Practices
    • Mobile Application (PWA)
  • Support
    • BotGhost Support
    • Frequently Asked Questions
  • Premium & Priority Hosting
    • Priority Hosting
    • Our Premium Features
    • Plans & Payment Methods
    • Manage Your Subscription
    • Upgrade Your Bot
    • Refund & Cancellation Policy
    • Beta Features
  • General Settings and Collaboration
    • Settings
    • Collab
    • Status
    • Active Developer Badge
    • Marketplace
  • Custom Commands & Events
    • Command & Event Builder
      • Sharing Commands and Events
      • Advanced Options
    • Actions
      • Message Actions
        • Send or Edit a Message
          • Button
          • Select Menu
        • Edit a Button or Select Menu
        • Send a Form
        • Delete a Message
        • Publish a Message
        • React to a Message
        • Pin a Message
      • Custom Variable Actions
        • Set Variable
        • Run Equation on Variable
        • Delete Variable
      • API Actions
        • Send an API Request
        • Execute an IFTTT Trigger
      • Loop Actions
        • Run a Loop
        • Stop a Loop
      • Voice Actions
        • Join a Voice Channel
        • Leave a Voice Channel
        • Voice Move a Member
        • Voice Kick a Member
        • Voice Mute or Unmute a Member
        • Voice Deafen or Undeafen a Member
      • Role Actions
        • Add Roles
        • Remove Roles
        • Create a role
        • Delete a role
        • Edit Role
      • Channel Actions
        • Create a channel
        • Edit a channel
        • Delete a channel
      • Thread and Forum Actions
        • Create a Thread
        • Edit a Thread
        • Delete a Thread
      • Server Actions
        • Kick a member
        • Ban a member
        • Timeout a member
        • Change a members nickname
        • Purge Messages
        • Create Server Invite
      • Other Actions
        • Wait before running another action
        • Manipulate some text
        • Send an error log message
        • Set a unique variable
        • Change the Bot's Status
        • Note
      • [LEGACY] Reply Actions
        • Plain Text Reply
        • Embed Reply
        • Random Reply
        • Send a message to a channel
        • Direct Message a User
        • Send a Message with attached buttons
          • Buttons
        • Send a message with a select menu
          • Menu Option
    • Conditions
      • Comparison Condition
      • Permission Condition
      • Chance Condition
      • Channel Condition
      • Role Condition
      • User Condition
      • Premium Check Condition
    • Options
      • Text Option
      • Number Option
      • User Option
      • Channel Option
      • Role Option
      • Choice Option
      • Attachment Option
    • Events
      • Timed Events
      • Webhooks
    • Data Storage
      • Collections
      • Objects
    • IFTTT
    • Variables
  • Server Management
    • Moderation
    • Discord Automod
    • Tickets
    • Welcomer
    • Verification
    • Statistic Channels
    • Modmail
    • Auto-React
    • Sticky Roles
    • Emoji Manager
    • Polls Filter
    • Automod
    • Logging
  • Messages
    • Timed Messages
    • Reaction Roles
    • Autoresponder
    • Embed Builder
    • Sticky Messages
    • Polls
    • Global Chat
    • Media Channels
  • AI
    • ChatGPT
    • Image Generation
  • Game Integrations
    • Roblox Verification
  • Social Integrations
    • YouTube
    • Twitch
  • Community Engagement
    • Leveling
    • Temp Voice Channels
    • Suggestions
    • Invite Tracker
    • Starboard
    • Question Of The Day
    • Giveaways
  • Fun Modules
    • Economy & Minigames
    • Birthdays
    • Counting
  • Utility
    • Translation
    • Weather
Powered by GitBook
On this page
  • API Key
  • Setting Up Webhooks
  • Creating a Webhook
  • Creating a Custom Event
  • Sending your POST request
  • API Reference

Was this helpful?

  1. Custom Commands & Events
  2. Events

Webhooks

Trigger custom events through webhooks

Last updated 5 months ago

Was this helpful?

allow you to trigger custom events by sending a POST HTTP request to the internal BotGhost API. This lets you connect external services and pass along data to your BotGhost hosted bot.

A BotGhost webhook is NOT the same as a .


API Key

To secure your webhook, the module requires you to authenticate with an API key. The owner of the bot can view, copy, and regenerate this key at any time on the Webhooks module. Treat this key like a password to your custom event, and only share it with those who should be able to trigger it.


Setting Up Webhooks

Creating a Webhook

To trigger an event from an external source you must first create a new webhook in your BotGhost dashboard. Enter a descriptive name for your webhook and click Add Webhook Event. An Event ID will be prepopulated and a new webhook will be created.

In the example request section of the newly created webhook, you will see the webhook URL and the required headers and body of the request. View the API reference at the bottom of the page for more information about the required information of the POST request.

Creating a Custom Event

Once you have created a webhook, you need to create a custom event to be executed when you submit a POST request to your webhook. This is the same process as creating a normal BotGhost custom event however you must select your webhook as an event type.

Go to the Custom Events module and create a new event. Select your webhook as the event type for your new event.

Once you have created your event, you must also set a server id as a base for the event. This is so it can retrieve information about channels and members when your event is executed.

After entering a server id, you can configure your custom event like normal. This event will be triggered when its associated webhook receives a valid HTTP POST request.

Sending your POST request

Once you have created a webhook and custom event you must send a POST request to the webhook URL.

The webhook URL is always in the format https://api.botghost.com/webhook/{bot_id}/{event_id} replacing {bot_id} with your bot's id and {event_id} with the generated webhook event id.

You must pass along your API token as an Authorization Header to authenticate your POST request.

You can also optionally pass along an array of variables to act as event variables with your request. The BotGhost Webhook API expects a JSON formatted array of objects with each variable object having:

Key
Info

name

A descriptive name for your variable.

variable

The actual variable itself. This must start with { and end with }.

value

The value of the variable that will be replaced when it is used in the webhook event.

Pass these variables along in the body of your request. You can then use any of these supplied variables in the custom event being executed by your webhook.


API Reference

Submit a POST request to the following endpoint. On success, if a custom event with that webhook event id exists that event will be triggered.

Replace {bot_id} and {event_id} in the URL with your bots id and a webhook event id.

POST https://api.botghost.com/webhook/{bot_id}/{event_id}

Send a POST request to trigger a custom event on a bot. Replace {bot_id} and {event_id} with your bot id and an event id. Event ids are generated after creating a webhook in the webhook module.

Headers

Name
Type
Description

Authorization*

API_KEY

Auhthorization header with your API_KEY from the webhooks module page.

Request Body

Name
Type
Description

variables

Array

An array of optional variables to pass along to the webhook. Each variable object should have a name, variable, and value.

Response

When you send your POST request to your BotGhost webhook, you may receive different status codes. These codes let you know whether the webhook event was successfully triggered, or if an error occurred. Below you can find detailed information about each status code, what it means, and what to do from there.

Success! This status is returned when the webhook event has successfully been triggered. If you didn't get the result you expected, double-check your event's logic and try again.

Error. This status is returned when the request hasn't been formatted properly.

What Went Wrong

The most common occurrences of this error happen when:

  • The variables parameter was not formatted as an array

  • The variables parameter was missing the name, variable, or value key(s)

  • The variables parameter had an improperly formatted variable key

How to Fix

Head back to the variables settings under Sending your POST request and try setting up again.

Error. This status is returned when the provided API key is invalid.

What Went Wrong

The most common occurrences of this error happen when:

  • The API key was not provided

  • The API key has been provided incorrectly

  • The API key has been regenerated

  • The bot has been removed from BotGhost

How to Fix

Head back to the API Key settings and try setting up again.

Error. This status is returned when the provided URL is invalid.

What Went Wrong

The most common occurrences of this error happen when:

  • The webhook URL has been provided incorrectly

  • The webhook event has been deleted

  • The bot has been removed from BotGhost

How to Fix

Head back to the webhook URL settings under Sending your POST request and try setting up again.

Error. This status is returned when you have sent an API request to your webhook that is not a POST request. To fix it, set your request type to POST and try again.

Error. This status is returned when you have sent too many requests to this URL in a too short amount of time. To fix it, wait a while before trying again.

BotGhost webhooks
Discord webhook