paulmataruso/zulip
1
0
Fork 0
mirror of https://github.com/zulip/zulip.git synced 2025-11-04 14:03:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

api docs: Update incoming-webhooks-overview.md.

Browse Source
This commit is contained in:
Rishi Gupta
2018-10-11 16:54:13 -07:00
parent 4abce1783f
commit 47cddf4acf
1 changed files with 58 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files

127
templates/zerver/api/incoming-webhooks-overview.md
View File

@@ -1,94 +1,83 @@
# Incoming webhook integrations # Incoming webhook integrations
An incoming webhook allows a third-party service to push data to you when something An incoming webhook allows a third-party service to push data to Zulip when
happens. It's different from making a REST API call, where you send a request something happens. The third-party service `POST`s to a special URL when it
to the service's API and wait for a response. With an incoming webhook, the third-party has something for you, and then your webhook integration handles that
service sends you an HTTP POST when it has something for you. Your webhook incoming data.
integration defines the URI the service uses to communicate with Zulip, and
handles that incoming data.
New Zulip webhook integrations can take just a few hours to write, New Zulip webhook integrations can take just a few hours to write,
including tests and documentation, if you use the right process. including tests and documentation, if you use the right process.
**For detailed instructions, check out the ["Hello World" webhook walkthrough]( ## Quick guide
webhook-walkthrough)**.
For a quick guide, read on. * Set up the
[Zulip development environment](https://zulip.readthedocs.io/en/latest/development/overview.html).
* First, use <http://requestb.in/> or a similar site to capture an * Use <https://webhook.site/> or a similar site to capture an example
example webhook payload from the service you're integrating. You webhook payload from the third-party service. Create a
can use these captured payloads to create a set of test fixtures `zerver/webhooks/<mywebhook>/fixtures/` directory, and add the captured
for your integration under `zerver/webhooks/mywebhook/fixtures/`. payload as a test fixture.
* Then write a draft webhook handler under `zerver/webhooks/`; there * Create an `Integration` object, and add it to `WEBHOOK_INTEGRATIONS` in
are a lot of examples in that directory. We recommend templating `zerver/lib/integrations.py`. Search for `webhook` in that file to find an
off a short one (like `stash` or `zendesk`), since the longer ones existing one to copy.
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).
* Then write a test for your fixture in the `tests.py` file in the * Write a draft webhook handler under `zerver/webhooks/`. There are a lot of
`zerver/webhooks/mywebhook` directory. You can now iterate on examples in that directory that you can copy. We recommend templating off
debugging the tests and webhooks handler until they work, all a short one, like `stash` or `zendesk`.
without ever needing to post directly from the service you're
integrating with to your Zulip development machine. You can run * Add a test for your fixture at `zerver/webhooks/<mywebhook>/tests.py`.
just the tests for one integration like this: Run the tests for your integration like this:
``` ```
test-backend zerver/webhooks/pagerduty/ tools/test-backend zerver/webhooks/<mywebhook>/
``` ```
*Hint: See Iterate on debugging the test and webhooks handler until it all
[this guide](https://zulip.readthedocs.io/en/latest/testing/testing.html) works.
for more details on the Zulip test runner.*
* Once you've gotten your incoming webhook working and passing a test, capture * Capture payloads for the other common types of `POST`s the third-party
payloads for the other common types of posts the service's webhook service will make, and add tests for them; usually this part of the
will make, and add tests for them; usually this part of the process is pretty fast.
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.
* Finally, write documentation for the integration; there's a * Document the integration (required for getting it merged into Zulip). You
[detailed guide][integration-docs-guide]. 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 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 * `zerver/webhooks/mywebhook/__init__.py`: Empty file that is an obligatory
your integration in the user interface. Generally this should be the logo of the part of every python package. Remember to `git add` it.
platform/server/product you are integrating. See [Documenting your * `zerver/webhooks/mywebhook/view.py`: The main webhook integration function
integration][integration-docs-guide] for details. as well as any needed helper functions.
* `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/fixtures/messagetype.json`: Sample json payload data * `zerver/webhooks/mywebhook/fixtures/messagetype.json`: Sample json payload data
used by tests. Add one fixture file per type of message supported by your used by tests. Add one fixture file per type of message supported by your
integration. See [Testing and writing tests]( integration.
https://zulip.readthedocs.io/en/latest/testing/testing.html) for details. * `zerver/webhooks/mywebhook/tests.py`: Tests for your webbook.
* `zerver/webhooks/mywebhook/__init__.py`: Empty file that is obligatory * `zerver/webhooks/mywebhook/doc.html`: End-user documentation explaining
part of every python package. Remember to `git add` it. how to add the integration.
* `zerver/webhooks/mywebhook/view.py`: Includes the main webhook integration * `static/images/integrations/logos/mywebhook.svg`: A square logo for the
function including any needed helper functions. platform/server/product you are integrating. Used on the documentation
* `zerver/webhooks/mywebhook/tests.py`: Add tests for your pages as well as the sender's avatar for messages sent by the integration.
webbook. See [Testing and writing tests]( * `static/images/integrations/mywebbook/001.svg`: A screenshot of a message
https://zulip.readthedocs.io/en/latest/testing/testing.html) for details. sent by the integration, used on the documenation page.
* `zerver/webhooks/mywebhook/doc.html`: Add end-user documentation. See
[Documenting your integration][integration-docs-guide] for details.
[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 * `zerver/lib/integrations.py`: Add your integration to
`WEBHOOK_INTEGRATIONS` to register it. This will automatically `WEBHOOK_INTEGRATIONS`. This will automatically register a
register a url for the incoming webhook of the form `api/v1/external/mywebhook` URL for the incoming webhook of the form `api/v1/external/mywebhook` and
and associate with the function called `api_mywebhook_webhook` in associate it with the function called `api_mywebhook_webhook` in
`zerver/webhooks/mywebhook/view.py`. `zerver/webhooks/mywebhook/view.py`.