mirror of https://github.com/zulip/zulip.git
95 lines
4.7 KiB
Markdown
95 lines
4.7 KiB
Markdown
# 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.
|
|
|
|
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)**.
|
|
|
|
For a quick guide, read on.
|
|
|
|
* First, use <http://requestb.in/> 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/`.
|
|
|
|
* 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).
|
|
|
|
* 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:
|
|
|
|
```
|
|
test-backend zerver/webhooks/pagerduty/
|
|
```
|
|
|
|
*Hint: See
|
|
[this guide](https://zulip.readthedocs.io/en/latest/testing/testing.html)
|
|
for more details on the Zulip test runner.*
|
|
|
|
* 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.
|
|
|
|
* Finally, write documentation for the integration; there's a
|
|
[detailed guide][integration-docs-guide].
|
|
|
|
## 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'.
|
|
|
|
* `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/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-docs-guide]: https://zulip.readthedocs.io/en/latest/subsystems/integration-docs.html
|
|
|
|
## 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`.
|