diff --git a/templates/zerver/api/incoming-webhooks-overview.md b/templates/zerver/api/incoming-webhooks-overview.md
index 0e5fc36c52..dde497e588 100644
--- a/templates/zerver/api/incoming-webhooks-overview.md
+++ b/templates/zerver/api/incoming-webhooks-overview.md
@@ -1,94 +1,83 @@
# Incoming webhook integrations
-An incoming webhook allows a third-party service to push data to you when something
-happens. It's different from making a REST API call, where you send a request
-to the service's API and wait for a response. With an incoming webhook, the third-party
-service sends you an HTTP POST when it has something for you. Your webhook
-integration defines the URI the service uses to communicate with Zulip, and
-handles that incoming data.
+An incoming webhook allows a third-party service to push data to Zulip when
+something happens. The third-party service `POST`s to a special URL when it
+has something for you, and then your webhook integration handles that
+incoming data.
New Zulip webhook integrations can take just a few hours to write,
including tests and documentation, if you use the right process.
-**For detailed instructions, check out the ["Hello World" webhook walkthrough](
-webhook-walkthrough)**.
+## Quick guide
-For a quick guide, read on.
+* Set up the
+ [Zulip development environment](https://zulip.readthedocs.io/en/latest/development/overview.html).
-* First, use or a similar site to capture an
- example webhook payload from the service you're integrating. You
- can use these captured payloads to create a set of test fixtures
- for your integration under `zerver/webhooks/mywebhook/fixtures/`.
+* Use or a similar site to capture an example
+ webhook payload from the third-party service. Create a
+ `zerver/webhooks//fixtures/` directory, and add the captured
+ payload as a test fixture.
-* Then write a draft webhook handler under `zerver/webhooks/`; there
- are a lot of examples in that directory. We recommend templating
- off a short one (like `stash` or `zendesk`), since the longer ones
- usually just have more complex parsing which can obscure what's
- common to all webhook integrations. In addition to writing the
- integration itself, you'll need to create `Integration` object and
- add it to `WEBHOOK_INTEGRATIONS` in `zerver/lib/integrations.py;`
- search for `webhook` in that file to find the existing ones (and
- please add yours in the alphabetically correct place).
+* Create an `Integration` object, and add it to `WEBHOOK_INTEGRATIONS` in
+ `zerver/lib/integrations.py`. Search for `webhook` in that file to find an
+ existing one to copy.
-* Then write a test for your fixture in the `tests.py` file in the
- `zerver/webhooks/mywebhook` directory. You can now iterate on
- debugging the tests and webhooks handler until they work, all
- without ever needing to post directly from the service you're
- integrating with to your Zulip development machine. You can run
- just the tests for one integration like this:
+* Write a draft webhook handler under `zerver/webhooks/`. There are a lot of
+ examples in that directory that you can copy. We recommend templating off
+ a short one, like `stash` or `zendesk`.
+
+* Add a test for your fixture at `zerver/webhooks//tests.py`.
+ Run the tests for your integration like this:
```
- test-backend zerver/webhooks/pagerduty/
+ tools/test-backend zerver/webhooks//
```
- *Hint: See
- [this guide](https://zulip.readthedocs.io/en/latest/testing/testing.html)
- for more details on the Zulip test runner.*
+ Iterate on debugging the test and webhooks handler until it all
+ works.
-* Once you've gotten your incoming webhook working and passing a test, capture
- payloads for the other common types of posts the service's webhook
- will make, and add tests for them; usually this part of the
- process is pretty fast. Webhook integration tests should all use
- fixtures (as opposed to contacting the service), since otherwise
- the tests can't run without Internet access and some sort of
- credentials for the service.
+* Capture payloads for the other common types of `POST`s the third-party
+ service will make, and add tests for them; usually this part of the
+ process is pretty fast.
-* Finally, write documentation for the integration; there's a
- [detailed guide][integration-docs-guide].
+* Document the integration (required for getting it merged into Zulip). You
+ can template off an existing guide, like
+ [this one](https://raw.githubusercontent.com/zulip/zulip/master/zerver/webhooks/github/doc.md).
+ This should not take more than 15 minutes, even if you don't speak English
+ as a first language (we'll clean up the text before merging).
-## Files that need to be created
+## Hello world walkthrough
+
+Check out the [detailed walkthrough](webhook-walkthrough) for step-by-step
+instructions.
+
+## Checklist
+
+### Files that need to be created
Select a name for your incoming webhook and use it consistently. The examples
-below are for a webhook named 'MyWebHook'.
+below are for a webhook named `MyWebHook`.
-* `static/images/integrations/logos/mywebhook.svg`: An image to represent
- your integration in the user interface. Generally this should be the logo of the
- platform/server/product you are integrating. See [Documenting your
- integration][integration-docs-guide] for details.
-* `static/images/integrations/mywebbook/001.svg`: A screen capture of your
- integration for use in the user interface. You can add as many images as needed
- to effectively document your webhook integration. See [Documenting your
- integration][integration-docs-guide] for details.
+* `zerver/webhooks/mywebhook/__init__.py`: Empty file that is an obligatory
+ part of every python package. Remember to `git add` it.
+* `zerver/webhooks/mywebhook/view.py`: The main webhook integration function
+ as well as any needed helper functions.
* `zerver/webhooks/mywebhook/fixtures/messagetype.json`: Sample json payload data
used by tests. Add one fixture file per type of message supported by your
- integration. See [Testing and writing tests](
- https://zulip.readthedocs.io/en/latest/testing/testing.html) for details.
-* `zerver/webhooks/mywebhook/__init__.py`: Empty file that is obligatory
- part of every python package. Remember to `git add` it.
-* `zerver/webhooks/mywebhook/view.py`: Includes the main webhook integration
- function including any needed helper functions.
-* `zerver/webhooks/mywebhook/tests.py`: Add tests for your
- webbook. See [Testing and writing tests](
- https://zulip.readthedocs.io/en/latest/testing/testing.html) for details.
-* `zerver/webhooks/mywebhook/doc.html`: Add end-user documentation. See
- [Documenting your integration][integration-docs-guide] for details.
+ integration.
+* `zerver/webhooks/mywebhook/tests.py`: Tests for your webbook.
+* `zerver/webhooks/mywebhook/doc.html`: End-user documentation explaining
+ how to add the integration.
+* `static/images/integrations/logos/mywebhook.svg`: A square logo for the
+ platform/server/product you are integrating. Used on the documentation
+ pages as well as the sender's avatar for messages sent by the integration.
+* `static/images/integrations/mywebbook/001.svg`: A screenshot of a message
+ sent by the integration, used on the documenation page.
-[integration-docs-guide]: https://zulip.readthedocs.io/en/latest/subsystems/integration-docs.html
-
-## Files that need to be updated
+### Files that need to be updated
* `zerver/lib/integrations.py`: Add your integration to
-`WEBHOOK_INTEGRATIONS` to register it. This will automatically
-register a url for the incoming webhook of the form `api/v1/external/mywebhook`
-and associate with the function called `api_mywebhook_webhook` in
-`zerver/webhooks/mywebhook/view.py`.
+ `WEBHOOK_INTEGRATIONS`. This will automatically register a
+ URL for the incoming webhook of the form `api/v1/external/mywebhook` and
+ associate it with the function called `api_mywebhook_webhook` in
+ `zerver/webhooks/mywebhook/view.py`.