Webhooks

What are BotGhost Webhooks?

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.

API Key

To authenticate your POST requests to your bot's webhooks you must pass along an API key as a Header. This API key can be regenerated and shown at the top of the webhooks page in your dashboard. Only the owner of the bot can see and regenerate API keys.

1. 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.

2. 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.

3. 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:

name - a descriptive name for your variable
variable - the actual variable itself. This must start with { and end with }.
value - the actual value of the variable.

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.