Once your code is ready to receive and process Mist Webhooks, it will listen for any delivery that is sent to the configured URL. As described previously, you web server listening for the Webhooks must be reachable to the Mist Cloud to be able to receive the HTTP POST messages.

It is possible to place the web server behind a Firewall, a WAF, or a reverse proxy to limit the web server exposition, but this approach may be complicated in the development process. To simplify the first steps, different "webhook relay" solutions exists, but this article will provide a quick overview of the Github smee.io solution.

Setup a webhook proxyCopy Anchor Link

This step is optional, and only required if your web server is not reachable by the Mist Cloud.

Get your webhook proxy URLCopy Anchor Link

1. With your web browser, got to https://smee.io/
2. Click Start a new channel, this will generate a new Unique URL for your session
3. Copy the full URL (e.g. https://smee.io/XXXXXXXXXX)

Forward your webhooksCopy Anchor Link

1. If you don't already have Node.js and NPM installed, download the Node.js installer and install it (this will also install NPM)
2. If you don't already have smee-client installed, run the following command in your terminal:

npm install --global smee-client

3. To receive forwarded webhooks from smee.io, run the following command in your terminal. Replace WEBHOOK_PROXY_URL with your webhook proxy URL from earlier.

smee --url WEBHOOK_PROXY_URL --path /collector --port 3000

4. You should see output that looks like this, where WEBHOOK_PROXY_URL is your webhook proxy URL:

Forwarding WEBHOOK_PROXY_URL to http://127.0.0.1:3000/collector
Connected WEBHOOK_PROXY_URL

Note: you can also customize the --path and --port options based on your requirements (these examples are matching the requirements for the [code samples]Webhook Security page).

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

Create the Webhook configurationCopy Anchor Link

1. Create a webhook configuration in your Mist Organization. For more information, see Configure a Webhook

Write the code to handle webhook deliveries.Copy Anchor Link

In order to handle webhook deliveries, your Webhook collector must:

1. Listen for HTTP POST messages sent by the Mist Cloud to your webhook URL
2. Read the HTTP headers and body from the request
3. Take the desired action in response to the request
4. Send a HTTP200 Response to the Mist Cloud to confirm the webhook delivery

Code samples for JavaScript and Python are available here. You can use these as a starting point, or create your own code.

Test the Webhook configuration and the Webhook collectorCopy Anchor Link

In order to validate your Webhook collector is able to receive (and process) the incoming webhooks, you can trigger an event in your Mist Organization or Site (specific to the selected topics) or you can trigger a webhook "Ping".

The Webhook "Ping" API Call can be used to manually trigger a webhook message. You can use the Ping Org Webhook (API Call) or Ping Site Webhook (API Call) to test the Mist Webhook configuration and your Webhook Collector.

To get an example of the webhook payload, see the Ping Webhook sample.

Check the Webhook DeliveriesCopy Anchor Link

For some Webhook Topics, Mist will keep the delivery information for 30 days. This information is available on the Mist UI and can be retrieved with the Search Org Webhooks Deliveries (API Call) (Org level) and Search Site Webhooks Deliveries (API Call) (Site level) API Endpoints.

These API Endpoints will let you retrive the list of Webhook messages the Mist Cloud tried to send to your Webhook collector, with the webhook headers and body, as the response status code, headers and body. If the Mist Cloud was not able to send the webhook or didn't receive any response from the collector, an error message will be added to describe the issue.

The list of Webhook Topics supporting the "Webhook Deliveries" history can be retrieved with the API Call List Webhook Topics by looking at the has_delivery_results key.