Mirror
/
zulip
mirror of https://github.com/zulip/zulip.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
zulip/templates/zerver/api/incoming-webhooks-overview.md

84 lines
3.4 KiB
Markdown
Raw Normal View History

api_docs: Split integration-guide.md into separate docs. This commit carves out the overview for incoming webhooks and moves it to its own file. This is a much better way to structure these docs. This is a quick follow-up to Tim Abbott's comment on #9592.
2018-07-04 02:08:27 +02:00
# Incoming webhook integrations
api docs: Update incoming-webhooks-overview.md.
2018-10-12 01:54:13 +02:00
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.
api_docs: Split integration-guide.md into separate docs. This commit carves out the overview for incoming webhooks and moves it to its own file. This is a much better way to structure these docs. This is a quick follow-up to Tim Abbott's comment on #9592.
2018-07-04 02:08:27 +02:00
New Zulip webhook integrations can take just a few hours to write,
including tests and documentation, if you use the right process.
api docs: Update incoming-webhooks-overview.md.
2018-10-12 01:54:13 +02:00
## Quick guide
* Set up the
[Zulip development environment](https://zulip.readthedocs.io/en/latest/development/overview.html).
* 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.
* 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.
* 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:
api_docs: Split integration-guide.md into separate docs. This commit carves out the overview for incoming webhooks and moves it to its own file. This is a much better way to structure these docs. This is a quick follow-up to Tim Abbott's comment on #9592.
2018-07-04 02:08:27 +02:00
```
api docs: Update incoming-webhooks-overview.md.
2018-10-12 01:54:13 +02:00
tools/test-backend zerver/webhooks/<mywebhook>/
api_docs: Split integration-guide.md into separate docs. This commit carves out the overview for incoming webhooks and moves it to its own file. This is a much better way to structure these docs. This is a quick follow-up to Tim Abbott's comment on #9592.
2018-07-04 02:08:27 +02:00
```
api docs: Update incoming-webhooks-overview.md.
2018-10-12 01:54:13 +02:00
Iterate on debugging the test and webhooks handler until it all
works.
* 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.
* 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).
api_docs: Split integration-guide.md into separate docs. This commit carves out the overview for incoming webhooks and moves it to its own file. This is a much better way to structure these docs. This is a quick follow-up to Tim Abbott's comment on #9592.
2018-07-04 02:08:27 +02:00
api docs: Update incoming-webhooks-overview.md.
2018-10-12 01:54:13 +02:00
## Hello world walkthrough
api_docs: Split integration-guide.md into separate docs. This commit carves out the overview for incoming webhooks and moves it to its own file. This is a much better way to structure these docs. This is a quick follow-up to Tim Abbott's comment on #9592.
2018-07-04 02:08:27 +02:00
api docs: Update incoming-webhooks-overview.md.
2018-10-12 01:54:13 +02:00
Check out the [detailed walkthrough](webhook-walkthrough) for step-by-step
instructions.
api_docs: Split integration-guide.md into separate docs. This commit carves out the overview for incoming webhooks and moves it to its own file. This is a much better way to structure these docs. This is a quick follow-up to Tim Abbott's comment on #9592.
2018-07-04 02:08:27 +02:00
api docs: Update incoming-webhooks-overview.md.
2018-10-12 01:54:13 +02:00
## Checklist
### Files that need to be created
api_docs: Split integration-guide.md into separate docs. This commit carves out the overview for incoming webhooks and moves it to its own file. This is a much better way to structure these docs. This is a quick follow-up to Tim Abbott's comment on #9592.
2018-07-04 02:08:27 +02:00
Select a name for your incoming webhook and use it consistently. The examples
api docs: Update incoming-webhooks-overview.md.
2018-10-12 01:54:13 +02:00
below are for a webhook named `MyWebHook`.
* `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.
api_docs: Split integration-guide.md into separate docs. This commit carves out the overview for incoming webhooks and moves it to its own file. This is a much better way to structure these docs. This is a quick follow-up to Tim Abbott's comment on #9592.
2018-07-04 02:08:27 +02:00
* `zerver/webhooks/mywebhook/fixtures/messagetype.json`: Sample json payload data
used by tests. Add one fixture file per type of message supported by your
api docs: Update incoming-webhooks-overview.md.
2018-10-12 01:54:13 +02:00
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.
### Files that need to be updated
api_docs: Split integration-guide.md into separate docs. This commit carves out the overview for incoming webhooks and moves it to its own file. This is a much better way to structure these docs. This is a quick follow-up to Tim Abbott's comment on #9592.
2018-07-04 02:08:27 +02:00
* `zerver/lib/integrations.py`: Add your integration to
api docs: Update incoming-webhooks-overview.md.
2018-10-12 01:54:13 +02:00
`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`.