# Tutorial: How to Configure Discord Webhooks Using the API

In a [previous article,](https://hookdeck.com/webhooks/platforms/tutorial-how-to-configure-discord-webhooks-using-the-admin-interface) we used the [Discord](https://discord.com/) web interface to set up a webhook on a Discord server. This webhook received commit updates from [GitHub](https://github.com/) and posted the information as a message to the channel it was assigned.

In this tutorial, we implement the same setup; however, this time we will be using the [Discord API](https://discord.com/developers/docs/intro) to set up our webhook. The [Discord API](https://discord.com/developers/docs/intro) offers more flexibility for integrating with Discord by allowing developers to interact with Discord within automated scripts and workflows.

If you're still new to Discord webhooks and would like to learn all about them and how they operate, [read this article](https://hookdeck.com/webhooks/platforms/how-to-get-started-with-discord-webhooks) before you proceed.

Excited about using the Discord API to set up your webhooks? Let's get started.

## Setup for receiving GitHub commit updates in Discord channels

Before we dive into the implementation of our integration of GitHub and Discord, let's take a few seconds to go through the requirements and steps that will be taken to achieve the integration.

To begin, the following accounts are required:

* A [Discord account](https://discord.com/register) you own
* A [GitHub](https://github.com/) account with a repository to experiment with
* A [Hookdeck](https://hookdeck.com/) account (you can sign up for a free account [here](https://dashboard.hookdeck.com/signup))
* An HTTP client tool (I will be using [Postman](https://www.postman.com/) for this tutorial)

Now that you have these in place, here are the steps you will take to create the communication flow between GitHub and Discord using webhooks created with the Discord API:

* Create a Discord server and set up a channel to receive the commit updates from GitHub
* Create a Discord application and add a bot to it with required permissions for creating webhooks
* Create a Discord webhook using the Discord API by authenticating with the Bot token
* Create a [Hookdeck](https://hookdeck.com/) connection to ingest your webhooks
* Create a GitHub webhook using the webhook URL from Hookdeck
* Test your connection

Sound easy? Let's get right into it!

## Creating a Discord server and channel

The first step is to create a Discord server and add a channel to it. To create a server, click on the plus (`+`) button on the side menu of your Discord interface. Then follow the server creation wizard (`Create my own` → `For me and my friends`) and enter a name for your server like below:

![Create a discord server](./images/create-a-discord-server.png)

Click the `Create` button to complete the process.

Next, add a channel to your server by clicking the `+` icon next to the `TEXT CHANNELS` label on the server menu. When a dialog pops up to enter a name for your channel, enter the value `webhooks-channel` like below, and click the `Create Channel` button.

![Create a discord channel](./images/create-a-discord-channel.png)

Now that you have created the channel, you need the channel ID. The channel ID can only be retrieved in developer mode, so you must click on the `User Settings` cog icon on the lower-left corner of your screen and click `Advanced` on the side menu. Here, you can turn on developer mode as shown below:

![enable discord developer mode](./images/enable-discord-developer-mode.png)

With developer mode on, you can now return to your Discord server and right-click on the `webhooks-channel` channel to copy the channel ID (click on `Copy ID` on the context menu).

## Creating a Discord bot

The next step is to create a Discord application and add a [Discord bot](https://hookdeck.com/) to the application. A Discord Bot (or a Discord bot account) is a special type of Discord user account dedicated to automation. Bot accounts have full access to all API routes without using bearer tokens, instead using a Bot token.

To create a Discord application, go to the [applications page](https://discordapp.com/developers/applications) and click the `New Application` button. Enter a name for your app like below:

![create discord app](./images/create-discord-app.png)

Click `Create` to complete the app creation process.

Once the application is created, go to `OAuth2` → `General` to copy the client ID. This ID will be required later on, so store it in a place where you can easily retrieve it.

Next, you need to add a bot to the application. Click `Bot` on the application menu and then click the `Add Bot` button (click `Yes, do it!` on the confirmation prompt). On the bot page, copy the bot token as shown below:

![Copy bot token](./images/copy-bot-token.png)

Next, scroll down to the `Bot Permissions` section and select `Manage Webhooks` like below:

![enable manage webhooks from bot permission](./images/enable-manage-webhooks-from-bot-permission.png)

This permission is required for you to create webhooks using the Discord API. Click the `Copy` button beside the `PERMISSIONS INTEGER` field. This permission integer is required to authenticate the bot.

To authenticate the bot to have access to the Discord API, enter the following URL in your browser (ensure to replace the `client_id` and `permissions_integer` with your values):

```jsx
https://discord.com/api/oauth2/authorize?client_id={{client_id}}&scope=bot&permissions={{permissions_integer}}

```

You can find more details about the bot authorization flow [here](https://discord.com/developers/docs/topics/oauth2#bot-authorization-flow). This URL will take you through the authorization process, where you will authorize the bot with the required permissions as shown below:

![authenticate discord bot](./images/authenticate-discord-bot.png)

![authorize discord bot permission](./images/authorize-discord-bot-permission.png)

A robot check might also be required, but once you pass that, you will get a message that your bot is now authorized.

## Creating a Discord webhook using the Discord API

Now let's create a Discord webhook using the Discord API. Enter the Discord webhooks API address shown below as your endpoint address:

```jsx
https://discordapp.com/api/channels/{{channel_id}}/webhooks

```

Remember to replace `channel_id` with your channel ID.

Select the `POST` request method and add the `Authorization` header using the format below:

```jsx
Authorization: Bot {{bot_token}}

```

`bot_token` is the token you copied from your Discord bot page.

The final item to add is the request body. Using the content-type of `application/json`, send the following request body:

```json
{
  "name": "my test webhook"
}

```

The `name` property is the name you wish to give your Discord webhook, and it is the only compulsory property. Check [here](https://discord.com/developers/docs/resources/webhook#create-webhook) for more details on creating webhooks using the API.

Now send the request and you will get a successful response, as shown below:

![Create discord webhook by sending api request using postman](./images/create-discord-webhook-by-sending-api-request-using-postman.png)
We have now successfully created a webhook for the `webhooks-channel` channel using the API.

One interesting thing I noticed the first time I created a webhook using the Discord API was that there was no webhook URL returned. According to the [Discord webhook object definition](https://discord.com/developers/docs/resources/webhook#webhook-object), a webhook URL should be returned. However, I noticed that the webhook ID and webhook token were returned (`id` and `token` fields in the response).

A Discord webhook URL takes the [format](https://discord.com/developers/docs/resources/webhook#get-webhook-with-token):

```json
https://discord.com/api/webhooks/{{webhook_id}}/{{webhook_token}}

```

Thus, you can easily construct your webhook URL using details from the API response.

## Setting up a connection in Hookdeck

The next step is to create a webhook connection in [Hookdeck](https://hookdeck.com/). A Hookdeck connection helps ingest the webhook requests coming from GitHub, and asynchronously sends them to Discord to ensure that no webhooks are dropped in the case of a spike in webhook traffic. This is considered a best practice for webhooks in production. Check out [this article](https://hookdeck.com/webhooks/guides/best-practices-deploy-webhooks-production) for more best practices for webhooks in production environments.

To create a connection on [Hookdeck](https://hookdeck.com/), go to `Connections` on your dashboard and click the `Create` button. Fill in the connection form fields as listed below.

* Source Name: `my-github-repository`
* Destination Name: `my-discord-channel`
* Destination URL: Your Discord Webhook URL
* Ruleset: `my-discord-ruleset`

The filled form is shown below as a reference.

![create webhook connection in Hookdeck](./images/create-webhook-connection-in-hookdeck.png)

Click the `Save` button to create your connection.

Your connection is now displayed in the list of connections, like below:

![Validate webhook connection is created](./images/validate-webhook-conenction-is-created.png)

Click the `Copy webhook URL` link on the connection source to get the Hookdeck webhook URL, as shown below:

![copy Source URL for discord webhook](./images/copy-source-url-for-discord-webhook.png)

This is the webhook URL you will need to set up your GitHub webhook.

## Setting up your GitHub repository to send commits to Discord

The next step is to set up a webhook on your GitHub repository. This webhook will be triggered anytime the `push` event is fired. A `push` event is fired when a new commit is made to the GitHub repository.

To set up the GitHub webhook, navigate to the repository you wish to use for this tutorial, then go to `Settings` → `Webhooks` and click the `Add Webhook` button on the `Webhooks` page. Fill the GitHub webhook form as follows:

* Payload URL: The webhook URL copied from Hookdeck with `/github` appended to it, i.e. `https://[MY-HOOKDECK-URL]/github`
* Content-type: `application/json`
* Secret: Leave this blank

Leave the remaining options on the form in their default state. A filled version of the webhook form is shown below.

![add webhook in Github](./images/add-webhook-in-github.png)

Do note once again to append `/github` to your Hookdeck, as this will ensure that Discord understands how to parse the payload sent by GitHub. This may not be applicable to all applications you want to integrate with Discord webhooks. To find information about the format for Discord webhook messages, check [this guide](https://discord.com/developers/docs/resources/webhook). You can also find more details about GitHub's integration with Discord [here](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks).

Click the `Add webhook` button to complete the GitHub webhook creation process. GitHub will automatically trigger a `ping` webhook request when a new webhook is created. You can ignore this `ping` request and move on to the next step.

## Testing your Discord webhook notifications

With the connection between Discord and GitHub established through Hookdeck, time to test the communication flow. Push a new update to your GitHub repository. Once pushed, check the `Connections` page on your Hookdeck dashboard, where you will see an event similar to the one below:

![Receive event in Hookdeck](./images/receive-event-in-hookdeck.png)

Clicking on the event will pull up the event details on a right-hand-side screen. However, to view the complete event details, you must click the arrow icon on the top right. On the full event page, you can view the webhook metadata, headers, and body as shown below:

Metadata

![github to discord event metadata in Hookdeck](./images/github-to-discord-event-metadata-in-hookdeck.png)

Headers

![github to discord event headers in Hookdeck](./images/github-to-discord-event-headers-in-hookdeck.png)

Body

![github to discord event body in Hookdeck](./images/github-to-discord-event-body-in-hookdeck.png)

[Hookdeck](https://hookdeck.com/) gives you the ability to inspect your webhooks down to the last detail.

Let's now confirm that the GitHub commit information is being sent to the Discord channel that was created. Return to your Discord account and click the `webhooks-channel` channel to view the messages in it. You will see a new GitHub message similar to the one shown below:

![confirm github notification in Discord channel](./images/confirm-github-notification-in-discord-channel.png)

Sleek, isn't it?

## Conclusion

APIs provide flexible ways for developers to integrate with [SaaS](https://en.wikipedia.org/wiki/Software_as_a_service) platforms. To learn about security considerations, check out our [guide to Discord webhooks features and best practices](/webhooks/platforms/guide-to-discord-webhooks-features-and-best-practices). Using the [Discord webhooks API](https://discord.com/developers/docs/resources/webhook), you can programmatically control how your webhooks are managed and also involve them in your automation workflows.

In this tutorial, you have learned how to use the Discord webhook API to create webhooks. The API also contains a bunch of endpoints for retrieving, editing, and deleting your webhooks. I encourage you to visit the [documentation](https://discord.com/developers/docs/resources/webhook) and play around with more endpoints, as well as other configuration options the API offers.

Happy coding!