api-docs: Document incoming webhook URL specification and generator.

Updates the shared integrations documentation on generating a URL for
an incoming webhook for the new modal in the web-app, with links to the
help center. Also, links to a new section in the incoming webhooks
overview in the API documentation about the URL specification.

Also, adds a link to the help center in the shared webhooks integration
instructions for creating a stream for an incoming webhook. And updates
the example webhook URL to use a stream ID instead of a stream name.

api_docs/incoming-webhooks-overview.md

@@ -155,3 +155,39 @@ below are for a webhook named `MyWebHook`.
   testing with live data from the service you're integrating and can help you
   spot why something isn't working or if the service is using custom HTTP
   headers.
+
+## URLs
+
+The base URL for an incoming webhook integration bot is
+`{{ api_url }}/v1/external/INTEGRATION_NAME?api_key=API_KEY` where
+`INTEGRATION_NAME` is the name of the specific webhook integration and
+`API_KEY` is the API key of the bot created by the user for the
+integration.
+
+The list of existing webhook integrations can be found in
+`zerver/lib/integrations.py` (at `WEBHOOK_INTEGRATIONS`) or by browsing
+the [Integrations documentation](/integrations).
+
+Parameters accepted in the URL include:
+
+* `api_key`: **Required**. The API key of the bot created by the user
+  for the integration. To get a bot's API key, see the [API
+  keys](/api/api-keys) documentation.
+
+* `stream`: The stream for the integration to send notifications to.
+  Can be either the stream ID or the [URL-encoded][url-encoder] stream
+  name. By default the integration will send direct messages to the
+  bot's owner.
+
+* `topic`: The topic in the specified stream for the integration to
+  send notifications to. The topic should also be
+  [URL-encoded][url-encoder]. By default the integration will have a
+  topic configured for stream messages.
+
+* `only_events`, `exclude_events`: Some incoming webhook integrations
+  support these parameters to filter which events will trigger a
+  notification. For details, see the integration's [integration
+  documentation](/integrations) page.
+
+[add-bot]: /help/add-a-bot-or-integration
+[url-encoder]: https://www.urlencoder.org/

templates/zerver/integrations/include/create-stream.md

@@ -1,2 +1,2 @@
-Create the stream you'd like to use for
+[Create the stream](/help/create-a-stream) you'd like to use for
 {{ integration_display_name }} notifications.

templates/zerver/integrations/include/event-filtering-instruction.md

@@ -1,6 +1,7 @@
 To filter the events that trigger the notifications, you can append
 either `&only_events=["event_a","event_b"]` or `&exclude_events=["event_a","event_b"]`
-(or both, with different events) to the URL with an arbitrary number of supported events.
+(or both, with different events) to the URL you generated with an arbitrary
+number of supported events.
 
 Below are the events that {{ integration_display_name }} bot supports:
 

templates/zerver/integrations/include/generate-integration-url.md

@@ -1,9 +1,19 @@
-Generate the URL for your integration by clicking the **link** (<i
+Generate the URL for your {{ integration_display_name }} integration,
-class="fa fa-link"></i>) icon on the profile card for the bot you
+with the stream (and topic) you want notifications sent to, by [viewing
-created.
+the bot you created](/help/view-your-bots) and clicking the **link**
+(<i class="fa fa-link"></i>) icon on the bot's profile card.
+
+The generated URL will be something like:
+
+{!webhook-url.md!}
+
+*To manually construct the URL for an incoming webhook integration,
+see [the webhook URLs specification][incoming-webhook-urls].*
 
 {% if all_event_types is defined %}
 
 {!event-filtering-instruction.md!}
 
 {% endif %}
+
+[incoming-webhook-urls]: /api/incoming-webhooks-overview#urls

templates/zerver/integrations/include/webhook-url.md

@@ -1 +1 @@
-`{{ api_url }}{{ integration_url }}?api_key=abcdefgh&stream=stream%20name`
+`{{ api_url }}{{ integration_url }}?api_key=abcdefgh&stream=123`