Webhooks
Trigger custom events through webhooks
Last updated
Trigger custom events through webhooks
Last updated
BotGhost webhooks 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 Discord webhook.
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.
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.
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.
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:
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.
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
Authorization*
API_KEY
Auhthorization header with your API_KEY from the webhooks module page.
Request Body
variables
Array
An array of optional variables to pass along to the webhook. Each variable object should have a name, variable, and value.
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.
