paulmataruso/zulip
1
0
Fork 0
mirror of https://github.com/zulip/zulip.git synced 2025-11-03 21:43:21 +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
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 <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/`.
* Use <https://webhook.site/> or a similar site to capture an example
webhook payload from the third-party service. Create a
`zerver/webhooks/<mywebhook>/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/<mywebhook>/tests.py`.
Run the tests for your integration like this:
```
test-backend zerver/webhooks/pagerduty/
tools/test-backend zerver/webhooks/<mywebhook>/
```
*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`.