Testing Webhooks

This will let you verify that Fluid sends a webhook delivery in response to an event that you expect to trigger a webhook delivery.

You can also test your code that handles webhook deliveries by using your computer as a local server and forwarding webhook deliveries to your local server. This will let you develop and debug your code without deploying your code to your production server.

Testing webhook delivery

You can trigger a webhook event and verify that Fluid sent a webhook delivery.

• Trigger your webhook. For example, if you are testing a Action webhook that is subscribed to the create event, create an Action in the board where the webhook is configured.

• If you are using an organization or repository webhook, you can also use the REST API to trigger the ping event for your webhook. 

• Check Fluid to verify that a webhook delivery was sent.

If a webhook delivery was not sent, or if a webhook delivery was sent but Fluid indicates that the delivery failed, refer to the troubleshooting guide to help diagnose the problem. For more information, see Troubleshooting webhooks

Testing webhook code locally

In order to test your webhook code locally on your computer, you can use a webhook proxy URL to forward webhooks from Fluid to your computer or codespace. You can use your computer as a local server to receive these forwarded webhooks.

The following sections demonstrate how to use ngrok http://ngrok.com to provide a webhook proxy URL and forward webhooks. Other alternatives such as http://smee.io can also be used.

For specific examples of code and testing steps, see  Handling webhook deliveries

Get a webhook proxy URL

1. In your browser, navigate to http://ngrok.com.
2. Sign up, if you have not already. Sign up is free
3. See https://ngrok.com/download to install ngrok.
4. In a cmd window, run ngrok http<port> where <port> is the port number that your local server is listening on.
5. Browse to the ngrok local dashboard at http://localhost:4040 to find your public URL information under the status tab.

For IISExpress running a localhost instance, you will need to configure the http-header as part of your ngrok configuration for ngrok to forward correctly. Replace [port] with the port number of your running instance.

ngrok http [port] --host-header="localhost:[port]"

Configure a webhook to use the webhook proxy URL

Configure your webhook to use the webhook proxy URL from above. For more information, see How to configure Webooks to Fluid Boards integration

Now, Fluid will send webhook deliveries to that URL.

Start a local server

On your computer, start a local server. The way that you do this depends on how your code to receive webhooks is written. For examples, see Handling webhook deliveries

You should make sure that your code can run locally. For example, if your code relies on environment variables on your server in production, you should make sure that the environment variables are also available on your local server.

You may also find it useful to add log statements so that you can verify that steps of your code executed as expected.

Keep your local server running while you test out your webhook.

Forward webhooks

1. If you don't already have ngrok installed, run the following command in your terminal:

choco install ngrok

2. To receive forwarded webhooks from ngrok, run the following command in your terminal. Replace PORT with the port where your local server is listening.

ngrok http PORT

For IISExpress running a localhost instance, you will need to configure the http-header as part of your ngrok configuration for ngrok to forward correctly. Replace [port] with the port number of your running instance. 
ngrok http [port] --host-header="localhost:[port]"

Now, when your webhook proxy URL (ngrok public URL found at http://localhost:4040) receives a webhook delivery from Fluid, ngrok will forward the webhook delivery to your local server.

3. Keep this running while you test out your webhook. When you want to stop forwarding webhooks, enter Ctrl+C.

At this point, you should have both your local server running and the ngrok forwarding running.

Trigger a webhook delivery

Trigger your webhook. For example, if you are testing a repository webhook that is subscribed to the issues event, open an issue in the repository where the webhook is configured.

Verify delivery

You can verify that Fluid sent a webhook delivery, that ngrok received and forwarded the delivery, and that your local server processed the webhook delivery.

Verify that Ngrok received your webhook delivery

Navigate to your ngrok dashboard at http://localhost:4040. Under the inspect tab, you should see an event that corresponds to the event that you triggered. This indicates that Fluid successfully sent a webhook delivery to the payload URL that you specified.

If you don't see your webhook delivery on ngrok, verify that your webhook is using your webhook proxy URL (ngrok URL found under the status tab of your ngrok dashboard http://localhost:4040).

Verify that your local server processed the webhook delivery

At this point, you have verified that Fluid sent a webhook delivery and that ngrok forwarded the delivery to your local server. Now, you should verify that your code processed the webhook delivery as expected. The way that you do this depends on how your code to receive webhooks is written. For examples, see  Handling webhook deliveries