Best practices
Follow these best practices to improve security and performance when using webhooks.
Subscribe to the minimum number of topics
To limit the load on your server, you should only subscribe to the webhook topics that you need. Some topics may generate a high volume of messages. This is especially the case for the location topics.
For more information about the list of available topics, see List Webhook Topics.
For more information about subscribing to Webhook Topics, see:
- Org level: Create Org Webhook and Update Org Webhook
- Site level: Create Site Webhook and Update Site Webhook
Disable the test Webhook Configurations when not in use
It is common to use publicly hosted third part solutions like webhook.site, smee.io or other when testing the Mist webhooks, either to just see the webhooks sent by Mist, or to act as a Webhook Proxy.
Make sure to delete or disable you Webhook configuration when your tests are finished to:
- Limit Security risks: By leaving an active webhook configuration on Webhook.site, you may inadvertently expose your service to unauthorized access or data exposure. This can happen if someone discovers and exploits the still-active webhook endpoint.
- Limit Resource usage: If the webhook configuration remains active, it will continue to consume resources (e.g., bandwidth, memory) even when not in use. Over time, this can add up and impact performance, lead to costs associated with resource utilization, or the third party solution can decide to deny all the messages coming from Mist.
Use the Webhook "Ping" to test the end-to-end communication
The Webhook "Ping" API Call can be used to manually trigger a webhook message. You can use the Ping Org Webhook or Ping Site Webhook to test the Mist Webhook configuration and your Webhook Collector.
To get an example of the webhook payload, see the Ping Webhook sample.
When using HTTP-POST webhook type, use a webhook secret
You should set a webhook secret for your webhook and verify that the signature of each webhook delivery matches the secret. This helps to ensure that the webhook delivery is from Mist. For more information, see Securing Webhooks with http-post type.
The webhook secret should be a random string of text with high entropy. You should securely store your webhook secret in a way that your server can access.
Use HTTPS and SSL verification
You should ensure that your server uses an HTTPS connection. By default, Mist will verify SSL certificates when delivering webhooks. Mist recommends that you leave SSL verification enabled.
Allow Mist Cloud IP Addresses
You can set up an IP allow list for your server, and add the IP addresses that Mist uses for webhook deliveries. This can block spoofed requests to your server.
The list of IP Addresses used are specific to each Cloud instance. To get the list of IP Addresses, see Juniper Mist Firewall Ports and IP Addresses for Firewall Configuration from the Juniper documentation.
Use the "Webhook Deliveries" endpoint for validation
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 (Org level) and Search Site Webhooks Deliveries (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.