From 6e6cbeb89dc3c57a00cde3b6b29a321cc8a139a2 Mon Sep 17 00:00:00 2001 From: Tomasz Kolek Date: Sat, 26 Nov 2016 00:25:05 +0100 Subject: [PATCH] Split webhooks doc and move to particular directories. --- templates/zerver/integrations.html | 1863 +---------------------- tools/check-templates | 5 + zerver/lib/integrations.py | 14 +- zerver/lib/test_helpers.py | 9 +- zerver/webhooks/airbrake/doc.html | 26 + zerver/webhooks/appfollow/doc.html | 40 + zerver/webhooks/beanstalk/doc.html | 27 + zerver/webhooks/bitbucket/doc.html | 39 + zerver/webhooks/bitbucket2/doc.html | 34 + zerver/webhooks/circleci/doc.html | 30 + zerver/webhooks/codeship/doc.html | 34 + zerver/webhooks/crashlytics/doc.html | 30 + zerver/webhooks/delighted/doc.html | 35 + zerver/webhooks/deskdotcom/doc.html | 120 ++ zerver/webhooks/freshdesk/doc.html | 236 +++ zerver/webhooks/github/doc.html | 53 + zerver/webhooks/github_webhook/doc.html | 36 + zerver/webhooks/gitlab/doc.html | 33 + zerver/webhooks/gosquared/doc.html | 39 + zerver/webhooks/hellosign/doc.html | 32 + zerver/webhooks/helloworld/doc.html | 31 + zerver/webhooks/heroku/doc.html | 51 + zerver/webhooks/ifttt/doc.html | 46 + zerver/webhooks/jira/doc.html | 45 + zerver/webhooks/librato/doc.html | 77 + zerver/webhooks/mention/doc.html | 52 + zerver/webhooks/newrelic/doc.html | 32 + zerver/webhooks/pagerduty/doc.html | 24 + zerver/webhooks/papertrail/doc.html | 45 + zerver/webhooks/pingdom/doc.html | 35 + zerver/webhooks/pivotal/doc.html | 35 + zerver/webhooks/semaphore/doc.html | 54 + zerver/webhooks/sentry/doc.html | 38 + zerver/webhooks/solano/doc.html | 32 + zerver/webhooks/stash/doc.html | 68 + zerver/webhooks/stripe/doc.html | 68 + zerver/webhooks/taiga/doc.html | 94 ++ zerver/webhooks/teamcity/doc.html | 58 + zerver/webhooks/transifex/doc.html | 32 + zerver/webhooks/travis/doc.html | 28 + zerver/webhooks/trello/doc.html | 87 ++ zerver/webhooks/updown/doc.html | 26 + zerver/webhooks/yo/doc.html | 33 + zerver/webhooks/zapier/doc.html | 42 + zerver/webhooks/zendesk/doc.html | 81 + zproject/settings.py | 1 + 46 files changed, 2088 insertions(+), 1862 deletions(-) create mode 100644 zerver/webhooks/airbrake/doc.html create mode 100644 zerver/webhooks/appfollow/doc.html create mode 100644 zerver/webhooks/beanstalk/doc.html create mode 100644 zerver/webhooks/bitbucket/doc.html create mode 100644 zerver/webhooks/bitbucket2/doc.html create mode 100644 zerver/webhooks/circleci/doc.html create mode 100644 zerver/webhooks/codeship/doc.html create mode 100644 zerver/webhooks/crashlytics/doc.html create mode 100644 zerver/webhooks/delighted/doc.html create mode 100644 zerver/webhooks/deskdotcom/doc.html create mode 100644 zerver/webhooks/freshdesk/doc.html create mode 100644 zerver/webhooks/github/doc.html create mode 100644 zerver/webhooks/github_webhook/doc.html create mode 100644 zerver/webhooks/gitlab/doc.html create mode 100644 zerver/webhooks/gosquared/doc.html create mode 100644 zerver/webhooks/hellosign/doc.html create mode 100644 zerver/webhooks/helloworld/doc.html create mode 100644 zerver/webhooks/heroku/doc.html create mode 100644 zerver/webhooks/ifttt/doc.html create mode 100644 zerver/webhooks/jira/doc.html create mode 100644 zerver/webhooks/librato/doc.html create mode 100644 zerver/webhooks/mention/doc.html create mode 100644 zerver/webhooks/newrelic/doc.html create mode 100644 zerver/webhooks/pagerduty/doc.html create mode 100644 zerver/webhooks/papertrail/doc.html create mode 100644 zerver/webhooks/pingdom/doc.html create mode 100644 zerver/webhooks/pivotal/doc.html create mode 100644 zerver/webhooks/semaphore/doc.html create mode 100644 zerver/webhooks/sentry/doc.html create mode 100644 zerver/webhooks/solano/doc.html create mode 100644 zerver/webhooks/stash/doc.html create mode 100644 zerver/webhooks/stripe/doc.html create mode 100644 zerver/webhooks/taiga/doc.html create mode 100644 zerver/webhooks/teamcity/doc.html create mode 100644 zerver/webhooks/transifex/doc.html create mode 100644 zerver/webhooks/travis/doc.html create mode 100644 zerver/webhooks/trello/doc.html create mode 100644 zerver/webhooks/updown/doc.html create mode 100644 zerver/webhooks/yo/doc.html create mode 100644 zerver/webhooks/zapier/doc.html create mode 100644 zerver/webhooks/zendesk/doc.html diff --git a/templates/zerver/integrations.html b/templates/zerver/integrations.html index 328dcd92bd..13f4e5d633 100644 --- a/templates/zerver/integrations.html +++ b/templates/zerver/integrations.html @@ -79,76 +79,15 @@
- -
- -

Get Zulip notifications for your Airbrake bug tracker!

- -

First, create the stream you'd like to use for Airbrake notifications, and - subscribe all interested parties to this stream. We recommend the - name airbrake.

- -

Next, on your {{ settings_html|safe }}, create an Airbrake bot. Construct the URL for - the Airbrake bot using the API key and stream name: - {{ external_api_uri_subdomain }}/v1/external/airbrake?api_key=abcdefgh&stream=airbrake -

- -

Now, go to your project's settings on the Airbrake site. Click - on the Integration section. - Choose Webhook, provide the above URL, - check Enabled, and save. Your Webhook - configuration should look similar to: -

- - -

Congratulations! You're done!
Your messages may look like:

- - -
- -
-

- Receive user reviews from your tracked apps on AppFolllow in Zulip - using the Zulip AppFollow plugin! -

- -

- First, create the stream you'd like to use for AppFollow notifications, and - subscribe all interested parties to this stream. We recommend the - name appfollow. -

- -

Next, on your {{ settings_html|safe }}, create an AppFollow bot.

- -

Then, log into your account on appfollow.io, and:

- -
    -
  1. -

    - Click on the app for which you'd like to receive reviews. - Click on Integrations and then go to the Others tab. -

    - - -
    2. -
  2. -

    - In the Webhook URL field, enter the following URL, replacing the bot API key - and Zulip stream with the appropriate information. -

    - -

    {{ external_api_uri_subdomain }}/v1/external/appfollow?api_key=test_api_key&stream=appfollow

    -
    3. -
- -

- Save changes – all done!
- New reviews for your app will be delivered to your Zulip stream. -

- - -
- + {% for integration in integrations_dict.values() %} + {% if integration.is_enabled() %} + {% if integration.doc %} +
+ {% include integration.doc %} +
+ {% endif %} + {% endif %} + {% endfor %}
@@ -252,84 +191,6 @@
-
- -

Zulip supports both SVN and Git notifications from Beanstalk.

- -

First, create the stream commits and subscribe all - interested parties to this stream.

- -

Next, in the Beanstalk web application, go to the Setup page and choose the Integrations tab. - Choose the Webhooks integration from the list presented. Make sure to replace the @ in the bot's email address with %40, - as Beanstalk's website will incorrectly refuse to parse a username containing a @.

- -

In the URL field, enter {{ external_uri_scheme }}bot_email:bot_api_key@{{ external_api_path_subdomain }}/v1/external/beanstalk:

- - -

Congratulations! You're done!
Whenever you do a - deployment, you'll get an automated notification that looks like - this:

- -
- -
- - -

Zulip supports both Git and Mercurial notifications from - Bitbucket. This integration is for the old-style Bitbucket - webhooks used by Bitbucket Enterprise.

- -

First, create the stream you'd like to use for Bitbucket notifications, - and subscribe all interested parties to this stream. The integration will - use the default stream commits if no stream is supplied in the - hook; you still need to create the stream even if you are using this - default.

- -

Next, from your repository's web page, go to the Administration page and choose Hooks on the left-hand side. - Choose the POST hook from the list presented and click "Add hook." Make sure to replace the @ in the bot's email address with %40, - as Bitbucket will not execute the hook if the username contains a @.

- -

In the URL field, enter {{ external_uri_scheme }}bot_email:bot_api_key@{{ external_api_path_subdomain }}/v1/external/bitbucket:

- - -

By default, notifications are sent to the commits stream. - To send notifications to a different stream, - append ?stream=stream_name to - the URL.

- -

Congratulations! You're done!
Whenever you push code to your repository, - you'll get an automated notification that looks like this:

- -
- -
- -

Zulip supports both Git and Mercurial notifications from - Bitbucket. This integration is for the new-style Bitbucket - webhooks used by the Bitbucket SAAS service.

- -

First, create the stream you'd like to use for Bitbucket notifications, - and subscribe all interested parties to this stream. The integration will - use the default stream bitbucket if no stream is supplied in the - hook; you still need to create the stream even if you are using this - default.

- -

The URL you create will be in the following format:

-

{{ external_api_uri_subdomain }}/v1/external/bitbucket2?api_key=abcdefgh&stream=bitbucket

- -

where api_key is the API key of your Zulip bot, - and stream is the stream name you want the - notifications sent to.

- -

Next, from your repository's web page, go to the Settings page and choose Webhooks on the left-hand side. - Click Add webhook, set URL to the URL you created above. Remember to click the 'active' checkbox. - Click Save.

- -

Congratulations! You're done!
- Example message:

- -
- -
- -

Zulip supports integration with CircleCI and can notify you of - your build statuses.

- -

First, create the stream you'd like to use for CircleCI notifications, - and subscribe all interested parties to this stream. We - recommend the name circleci.

- -

{{ external_api_uri_subdomain }}/v1/external/circleci?api_key=abcdefgh&stream=circleci

- -

where api_key is the API key of your Zulip bot, - and stream is the stream name you want the - notifications sent to.

- -

- Next, modify your circle.yml as described - here. -

- -

Congratulations! You're done!
When a build is done, - you'll get a notification like this:

- - - -
-

First, create the streams you'd like to use for Codebase notifications. There will be two types of @@ -440,200 +274,6 @@

-
- -

Zulip supports integration with Codeship and can notify you of - your build statuses.

- -

First, create the stream you'd like to use for Codeship notifications, - and subscribe all interested parties to this stream. We - recommend the name codeship.

- -

{{ external_api_uri_subdomain }}/v1/external/codeship?api_key=abcdefgh&stream=codeship

- -

where api_key is the API key of your Zulip bot, - and stream is the stream name you want the - notifications sent to.

- -

Next, go to your project settings - notification settings - page. The url should look like the following:

-

https://codeship.com/projects/PROJECT_ID/configure_notifications

-

where PROJECT_ID is the id of your project in Codeship.

-

Scroll to the Webhook section and fill out the form as follows:

- - -

Congratulations! You're done!
When a build is - triggered, you'll get a notification like this:

- - - -
- -
- -

Zulip supports integration with Crashlytics and can notify you - about Crashlytics issues.

- -

First, create the stream you'd like to use for Crashlytics notifications, - and subscribe all interested parties to this stream. We - recommend the name crashlytics.

- -

{{ external_api_uri_subdomain }}/v1/external/crashlytics?api_key=abcdefgh&stream=crashlytics

- -

where api_key is the API key of your Zulip bot, - and stream is the stream name you want the - notifications sent to.

- -

Click on the app in - your Crashlytics settings panel. - Next, on the integrations subpage, click “Web Hook,” enter the URL we created above and click - Verify.

-

Congratulations! You're done!
When an issue occurs, - you'll get a notification like this:

- - - -
- -
- -

- Zulip supports integration with Delighted and can notify you - about updates in feedback responses organized by Delighted. -

- -

- First, create the stream you'd like to use for Delighted notifications, - and subscribe all interested parties to this stream. We - recommend the name delighted. Next, create a bot named Delighted - and retrive the API key of the bot and place it into the API parameter in the URL below. -

- -

{{ external_api_uri_subdomain }}/v1/external/delighted?api_key=abcdefgh&stream=delighted

- -

- Modify the parameters of the URL above, where api_key is the API key of your Zulip bot, - and stream is the stream name you want the - notifications sent to. -

- -

- Go to your Delighted Webhook Integration settings panel. - Under Send webhook notifications for:: input the above URL with the modifications into - the URL textbox and press Save and turn on to finish. -

- - - -

- Congratulations! You're done!
When an issue occurs, - you'll get a notification like this: -

- - - -
- -
- - -

First, create the stream you'd like to use for Desk.com notifications, - and subscribe all interested parties to this stream. We recommend the - stream name desk. Keep in mind you still need to - create the stream first even if you are using this recommendation.

- -

Next, in Desk.com, open your Admin view via the top-left corner - dropdown. In the Admin view, click on Apps, then click Install under - "Custom Action":

- - -

From there, click "Install Custom Action" and accept the terms. Fill - in the form like this:

-
    -
  • Name: Zulip
    • -
  • Authentication Method: Basic Auth
    • -
  • URL: {{ external_api_uri_subdomain }}/v1/external/deskdotcom
    • -
  • User name: your bot's user name, e.g. desk-bot@yourdomain.com
    • -
  • Password: your bot's API key
    • -
- - - -

Click Create to save your settings. From the next screen, click Add - Action add a new action. You'll do this for every action you want a - notification on Zulip for. (To add another action later, look for your - custom action on the Apps page under "Installed Apps."

- - - -

Let's say you want a notification each time a case is updated. Put - in a descriptive name like "Announce case update", select "POST a string to a URL" - for Action Type, and copy-paste this to the "Appended URL path":

- {% raw %} -

?stream=desk&topic={{case.id}}:+{{case.subject}}

- {% endraw %} -

The "appended URL path" will be the same for every notification — - it makes sure the notification goes to the appropriate stream and topic - within Zulip.

- -

Next, copy this template Zulip message into "Message to - POST":

- {% raw %} - 
Case [{{case.id}}, {{case.subject}}]({{case.direct_url}}), was updated.
-
-* Status: {{case.status.name}}
-* Priority: {{case.priority}}
-* Customer: {{customer.name}}
-* Company: {{customer.company}}
-* Description: {{case.description}}
-

You don't need to edit that, although you may if you wish. All - the funny-looking stuff inside {{ and }} - will be filled in by Desk.com for each event. The dialog should look - like this:

- {% endraw %} - - - -

Click Add Action to save, and then on the next screen click the slider - next to the action to enable it. This is important — actions are turned off - by default!

- - - -

Now you need to create a rule that triggers this action. Desk.com's - support center has a - lengthy - article on rules, but in short, click on "Cases" up at the top, - "Rules" on the left side, and then the specific event you want to notify - on — in our example, "Inbound Interaction".

- - - -

Select the types of interaction you want your rule to apply to, - such as Chat. Specify the name and click on "Add Rule."

- - - -

In the next screen, provide the details. First, click Add Actions to - display the rule actions. Select "Trigger an App Action" in the dropdown, and - then the name of the custom action you created earlier when the second - dropdown appears. You can add additional "All" or "Any" conditions if desired. - Also select when the rule should run (if not "Anytime") and enable it.

- - - -

Finally, click Update.

- -

Congratulations! You're done!
When a case is updated, - you'll see a notification like the following, to the stream - desk, with a topic that matches the case's subject name:

- - - -
- - {% if email_integration_enabled %}
@@ -666,192 +306,6 @@
{% endif %} - -
-

Freshdesk

- -

See customer support interactions right in Zulip, with our Freshdesk - integration! Note that this integration must be set up by an administrator - for your Freshdesk instance.

- -

First, create the stream you'd like to use for Freshdesk notifications, - and subscribe all interested parties to this stream. We recommend the - stream name freshdesk.

- -

Next, on your {{ settings_html|safe }}, create a Freshdesk bot.

- -

Now we can set up the Freshdesk events that will trigger - Zulips. Freshdesk provides separate triggering mechanisms for ticket - creation and ticket changes, so we'll set up these triggers in two - parts.

- -

Part 1: Zulip notifications for new Freshdesk tickets

- -
    -
  1. -

    Visit your Freshdesk admin page. Under the "Helpdesk - Productivity" section, click the "Dispatch'r" icon:

    - - - -

    Click the "New rule" button to create a new Dispatch'r rule - that will send notifications to Zulip when Freshdesk tickets are - opened.

    -
    2. -
  2. -

    On the Dispatch'r rule creation page, give the rule a name and - description. Next, we need to specify the conditions under which to - trigger Zulip notifications. There isn't a shortcut for "always - generate a notification on ticket creation", so we'll instead fake it - by picking two complementary conditions: when the source is - email, and when the source is not email:

    - - -
    3. -
  3. - -

    In the "Action" section, add a new action of - type "Trigger Webhook". Set the "Request Type" - to "POST". Set the following "Callback URL", replacing - the Zulip stream with your desired stream:

    - -

    {{ external_api_uri_subdomain }}/v1/external/freshdesk?stream=freshdesk

    - -

    Check the "Requires Authentication" box, and supply the bot - e-mail address and API key.

    - -

    The Action section should look like this so far:

    - - -
    4. -
  4. -

    Select "JSON" for the "Encoding". Under the encoding, select - "Advanced". Paste the following JSON into the "Content" - box:

    - - 
    {"freshdesk_webhook":
-    {
-        "triggered_event":"{{triggered_event}}",
-        "ticket_id":"{{ticket.id}}",
-        "ticket_url":"{{ticket.url}}",
-        "ticket_type":"{{ticket.ticket_type}}",
-        "ticket_subject":"{{ticket.subject}}",
-        "ticket_description":"{{ticket.description}}",
-        "ticket_status":"{{ticket.status}}",
-        "ticket_priority":"{{ticket.priority}}",
-        "requester_name":"{{ticket.requester.name}}",
-        "requester_email":"{{ticket.requester.email}}",
-    }
-}
    - -

    These ticket details are what will be forwarded to Zulip. The - pasted JSON should look like this:

    - - -
    5. -
  5. -

    Save your new Dispatch'r rule. The next time a Freshdesk ticket is - opened, the team will get a notification in Zulip!

    -
    6. -
- -

If you only want to receive Zulip notifications on ticket creation, - stop here, you're done! If you also want notifications on important ticket - changes, please continue to the next section.

- -

Part 2: Zulip notifications on ticket changes

- -
    -
  1. -

    Visit your Freshdesk admin page. Under the "Helpdesk - Productivity" section, click the "Observer" icon:

    - - - -

    Click the "New rule" button to create a new Observer rule - that will send notifications to Zulip when Freshdesk tickets are - updated.

    -
    2. -
  2. -

    On the Observer rule creation page, give the rule a name and - description. Under "When Any Of These Events Occur", create - these new rules:

    -
      -

    • Priority is changed, from Any Priority, to Any Priority

      • -

    • Status is changed, from Any Status, to Any Status

      • -

    • Note is added, Type Any

      • -
    - -

    If you do not want to receive Zulip notifications on one or more of - these events, leave out the rule for that event.

    - -

    Under "And The Events Are Performed By", - select "Anyone".

    - -

    So far, the rule should look like this:

    - - -
    3. -
  3. -

    Next, we need to specify the types of tickets that will trigger - Zulip notifications. There isn't a shortcut for "always generate a - notification on ticket update", so as before we'll instead fake it by - picking two complementary conditions: when the source is email, - and when the source is not email:

    - - -
    4. -
  4. -

    Under "Perform These Actions", add a new action of - type "Trigger Webhook". Set the "Request Type" - to "POST". Set the following "Callback URL", replacing - the Zulip stream with your desired stream:

    - -

    {{ external_api_uri_subdomain }}/v1/external/freshdesk?stream=freshdesk

    - -

    Check the "Requires Authentication" box, and supply the bot - e-mail address and API key.

    - -

    The Action section should look like this so far:

    - - -
    5. -
  5. -

    Select "JSON" for the "Encoding". Under the encoding, - select "Advanced". Paste the following JSON into - the "Content" box:

    - - 
    {"freshdesk_webhook":
-    {
-        "triggered_event":"{{triggered_event}}",
-        "ticket_id":"{{ticket.id}}",
-        "ticket_url":"{{ticket.url}}",
-        "ticket_type":"{{ticket.ticket_type}}",
-        "ticket_subject":"{{ticket.subject}}",
-        "ticket_description":"{{ticket.description}}",
-        "ticket_status":"{{ticket.status}}",
-        "ticket_priority":"{{ticket.priority}}",
-        "requester_name":"{{ticket.requester.name}}",
-        "requester_email":"{{ticket.requester.email}}",
-    }
-}
    -

    These ticket details are what will be forwarded to Zulip. The - pasted JSON should look like this:

    - - -
    6. -
  6. -

    Save your new Observer rule. The next time a Freshdesk ticket is - updated, the team will get a notification in Zulip!

    -
    7. -
- -

Congratulations! You're done!
You'll now see support - progress in real time in Zulip:

- - -
- -
-

- This webhook bases on deprecated concept that is - GitHub Services -

- -

First, create the stream you'd like to use for GitHub notifications, - and subscribe all interested parties to this stream. The integration will - use the default stream commits if no stream is supplied in - the hook; you still need to create the stream even if you are using this - default.

- -

Next, go to your repository page and click "Settings":

-

- -

From there, select "Webhooks & Services":

-

- -

To find the Zulip hook, you have to click on Configure services.

-

- -

Select "Zulip" from the list of service hooks. Fill in - the API key and email address for your bot and check - the "active" checkbox. Specify - {{ external_api_uri_subdomain }}/v1/external/github as the "Alternative - endpoint". You can optionally supply the Zulip stream (the - default is commits) and restrict Zulip - notifications to a specified set of branches.

- -

Further configuration is possible. By default, commits traffic (pushes, commit comments), - GitHub issues traffic, and pull requests are enabled. You can exclude certain types of traffic - via the checkboxes. If you want commit traffic, issue traffic, and pull requests to go to - different places, you can use the Commit Stream and Issue Stream overrides; - otherwise, it is safe to leave these fields blank and just have it default to the Stream - setting.

- -

Click the "Update settings" button to complete the - configuration:

-

- -

Congratulations! You're done!
When team members push to - your repository, you'll get a Zulip notification that looks like this:

- -

- -
- -
- -

First, create the stream you'd like to use for GitHub Webhook notifications, - and subscribe all interested parties to this stream. The integration will - use the default stream github if no stream is supplied in - the hook; you still need to create the stream even if you are using this - default.

- -

Next, go to your repository page and click "Settings":

-

- -

From there, select "Webhooks":

-

- -

Click "Add webhook".

-

- -

Authorize yourself and configure your webhook.

- -

In the "Payload URL" field, enter a URL constructed like this:

- -

{{ external_api_uri_subdomain }}/v1/external/github?api_key=abcdefgh&stream=github

- -

where api_key is the API key of your Zulip - bot. Select the actions that you want to result in a - Zulip notification and click Add Webhook.

- -

Congratulations! You're done!
- Your messages will look like this:

- -

- -
- -
- -

First, create the stream you'd like to use for GitLab notifications, - and subscribe all interested parties to this stream. The integration will - use the default stream gitlab if no stream is supplied in - the URL; you still need to create the stream even if you are using this - default.

- -

Next, go to your repository page and click gear icon. - From there, select Webhooks:

-

- -

In the URL field, enter a URL constructed like this: - -

{{ external_api_uri_subdomain }}/v1/external/gitlab?api_key=abcdefgh&stream=gitlab

- -

where api_key is the API key of your Zulip - bot.

Select the actions that you want to result in a - Zulip notification and click Add Webhook.

- -

Congratulations! You're done!
- Your messages will look like this:

- -

- -
- -
- -

- First, create a stream for GoSquared for where you would like to receive GoSquared notifications - and subscribe all interested parties to the stream. The integration will automatically - use the default stream gosquared if no stream is supplied, though you will - still need to create the stream manually even though it's the default. -

- -

- Next, go to the Zulip settings page and create a bot named GoSquared. Go to the account settings page of - your GoSquared account and under Project Settings > Services > Webhook > Add New. - Add the below URL under the section 'Enter a URL to receive requests:' and name the integration, Zulip. -

- -

{{ external_api_uri_subdomain }}/v1/external/gosquared?api_key=abcdefgh&stream=gosquared

- -

- -

- Note: api_key must be reconfigured to be the API key of your Zulip bot.
- If you want to change the stream default that receives notifications, change stream= in the URL.
- To change the topic displayed by the bot, simply append &topic=name to the end of the above URL. - Where name is your topic. -

- -

- Under notifications of your GoSquared account page, press Add New Notification and select when and why you - want to be notified through Zulip. After you're done, remember to check the box of the webhook corresponding to Zulip. -

- -

- Congratulations! You're all set
- Your messages should look like this: -

- -

- -
-

@@ -1136,126 +442,6 @@

-
- -

- Configuring the HelloSign integration is easy. First, create a stream - (we recommend a name like "hellosign"). -

- -

- Next, go to the Zulip settings page and create a Zulip bot bot - for the HelloSign integration. Note the bot API key and add - it to the URL below as api_key, and including the - name of the stream you'd like to receive the notifications - as stream= in the URL. If you'd like to hardcode - the topic used by the bot, simply append - &topic=topic_name to the end of the above URL, where - topic_name is your topic. -

- -

{{ external_api_uri_subdomain }}/v1/external/hellosign?api_key=abcdefgh&stream=stream_name

- -

- Go to the account settings page of your HelloSign account and - under the Integrations tab, go to API and Account Callback. - Add the above URL with your modifications under the section 'Account Callback'. -

- -

- -

- Congratulations! You're all set.
- Your messages should look like this: -

- -

- -
- -
- -

Learn how Zulip integrations work with this simple Hello World example!

- -

The Hello World webhook will use the test stream, which is - created by default in the Zulip dev environment. If you are running - Zulip in production, you should make sure this stream exists.

- -

Next, on your {{ settings_html|safe }}, create a Hello World bot. Construct the URL for - the Hello World bot using the API key and stream name: - {{ external_api_uri_subdomain }}/v1/external/helloworld?api_key=abcdefgh&stream=test -

- -

To trigger a notication using this webhook, use `send_webhook_fixture_message` from the Zulip command line:

-
- 
(zulip-venv)vagrant@vagrant-ubuntu-trusty-64:/srv/zulip$
-./manage.py send_webhook_fixture_message \
-> --fixture=zerver/fixtures/helloworld/helloworld_hello.json \
-> '--url=http://localhost:9991/api/v1/external/helloworld?api_key=<api_key>'
-
- -

Or, use curl:

-
- 
curl -X POST -H "Content-Type: application/json" -d '{ "featured_title":"Marilyn Monroe", "featured_url":"https://en.wikipedia.org/wiki/Marilyn_Monroe" }' http://localhost:9991/api/v1/external/helloworld\?api_key\=<api_key>
-
- -

Congratulations! You're done!
Your messages may look like:

- - -
- -
-

- Receive notifications in Zulip whenever a new version of an app is pushed to Heroku - using the Zulip Heroku plugin! -

- -

- First, create the stream you'd like to use for Heroku notifications, and - subscribe all interested parties to this stream. We recommend the - name heroku. -

- -

Next, on your {{ settings_html|safe }}, create a Heroku bot.

- -

Then, log into your account on heroku.com, and:

- -
    -
  1. -

    - Visit the page for the project for which you'd like to generate - Zulip notifications. Click the "Resources" tab, and add the "Deploy Hooks" addon. - Choose the "HTTP Post Hook" plan, and click "Provision". -

    - - -
    2. -
  2. -

    - Click on the "Deploy Hooks" add-on that you just added. - You should be redirected to a page that looks like this: -

    - -

    - -

    - Enter the following webhook URI, replacing the bot API key - and Zulip stream with the appropriate information. -

    - -

    {{ external_uri_scheme }}{{ external_api_path_subdomain }}/v1/external/heroku?api_key=test_api_key&stream=heroku

    -
    3. -
- -

- Congratulations! You're done!
- When you deploy to Heroku, the team can see these updates in real time in Zulip: -

- - -
- -
@@ -1345,82 +531,6 @@

-
-

Get notifications from every event supported by IFTTT.

-

First, create the stream you'd like to use for IFTTT notifications, - and subscribe all interested parties to this stream.

- -

{{ external_api_uri_subdomain }}/v1/external/ifttt?api_key=abcdefgh&stream=ifttt

- -

Next, create an IFTTT recipe, picking the service you'd like - to receive notifications from as this, - and Maker as that.

- -

Choose the Make a web request action, and - configure it as follows:

- -
    -
  • URL is the url we created above
    • -
  • method is POST
    • -
  • Content Type is application/json
    • -
-

Finally, configure the request body. You need to construct a JSON - object with two parameters: content - and subject.
- Example: - {"content": "message content", "subject": "message subject"} -
-

-

You will most likely want to specify some IFTTT - "Ingredients" (click the beaker to see the available - options) to customize the subject and content of your - messages; the below screenshot uses ingredients available - if this is IFTTT's incoming email service. -

-

Example configuration: - -

- -

You're done! Example message:

- - -
- -
- - -

If you are running JIRA version 5.2 or greater, or if you are - using the hosted JIRA provided by Atlassian, you can use the built-in - web-hook support to connect to Zulip — read on. For older, - self-hosted JIRA installs, you can use our JIRA Plugin.

- -

First, create the stream you'd like to use for JIRA notifications, and - subscribe all interested parties to this stream. We recommend the - name jira.

- -

In your JIRA administration control panel, go to the Webhooks page. If you are using the OnDemand - hosted JIRA, follow the instructions - on the Atlassian wiki for locating the Webhook UI. -

-

Give your new web hook a name, and for the URL provide the following:

-

- {{ external_api_uri_subdomain }}/v1/external/jira?api_key=abcdefgh&stream=jira -

- -

where api_key is the API key of your Zulip bot, - and stream is the stream name you want the - notifications sent to.

- -

Next, go back to Zulip and set up a stream called "jira," if it does not already exist. - (If you prefer your JIRA notifications to go to a stream other than "jira," then change the URL above to match it.)

- -

Congratulations! You're done!
- Updates from JIRA will be sent to the Zulip stream you specified in the JIRA web-hook. -

- -
-
@@ -1470,123 +580,6 @@
-
- -

Get Zulip notifications for your Librato alerts or snapshots!

- -

First, create the stream you'd like to use for Librato notifications, and - subscribe all interested parties to this stream. We recommend the - name librato.

- -

Next, on your Zulip settings - page, create a Librato bot. Please note the bot name and API key. Then:

- -

Alerts configuration

- -

1. Login into your Librato account and switch to the integrations page:

-

- -

2. From there, select "Webhook" integration:

-

- -

3. Fill in the title and URL fields using your bot's API key

-

- -

The default stream name is librato and default topic name is Alert alert_name.

- - 
-      URL = {{ external_api_uri }}/v1/external/librato?api_key=your_api_key
- -

You can customize the stream name and topic name:

- - 
-      URL = {{ external_api_uri }}/v1/external/librato?stream=your_stream_name&topic=your_topic_name&api_key=your_api_key
- - -

4. Next, go to your alerts page:

-

- -

5. Choose the alert conditions and enable the your new - webhook under "Notification Services":

-

- -

- Congratulations! You're done!
- When an alert triggers, you'll get a Zulip notification that looks like this: -

- -

- - -

Snapshot configuration

- -

- Because of limitations in Librato's API, you need to use the - Slack integration to get Librato snapshots sent into Zulip. -

-

-

Default stream name is librato and default topic name is snapshots.

- -

- To send a snapshot, just click at one of your chart, use - the send a snapshot option and add the proper - integration. -

- -

- -

- Congratulations! You're done!
- When a snapshot comes, you'll get a Zulip notification that looks like this: -

- -

- -
- -
- -

First, create the stream you'd like to use for Mention Webhook notifications, - and subscribe all interested parties to this stream. The integration will - use the default stream mention if no stream is supplied in - the hook; you still need to create the stream even if you are using this - default.

- -

Next, go to your Mention feed and click on your profile in the top right corner, - click on Settings in the drop down menu:

-

- -

From there, select Integrations:

-

- -

Select the Zapier integration, and click Explore Mention on Zapier!:

-

- -

Search for "webhooks" in the search bar, and click on Webhooks by Zapier.
- Scroll down and look for Add Webhooks posts for new Mentions and click on - Use this Zap:

-

- -

Select your Mention account Id and the alert that should trigger mentions - from the respective drop down menus, and click Continue

- -

Select POST on the page that says Webhooks by Zapier Action, and click - Continue.

- -

In the URL field, enter a URL constructed like this:

- -

{{ external_api_uri_subdomain }}/v1/external/mention?api_key=abcdefgh&stream=mention

- -

where abcdefgh should be replaced with the API key of your Zulip - bot. Select JSON for Payload Type and click Continue:

- -

Congratulations! You're done!
- Your messages will look like this:

- -

- -
-

Get Zulip notifications when you hg push!

@@ -1751,34 +744,6 @@ key = NAGIOS_BOT_API_KEY directly.

- -
- - -

New Relic can send messages to a Zulip stream for alerts and - deploys.

- -

First, create the stream you'd like to use for New Relic - notifications, and subscribe all interested parties to this stream. We - recommend the name newrelic.

- -

Next, in your New Relic Account Settings page, click - "Integrations", then "Alerting notifications". On the "Webhook" - tab, enter the following webhook URL:

- -

{{ external_api_uri_subdomain }}/v1/external/newrelic?api_key=abcdefgh&stream=newrelic

- -

where api_key is the API key of your Zulip bot, - and stream is the stream name you want the - notifications sent to.

- - - -

Congratulations! You're done!
Your New Relic events will - appear in Zulip:

- -
-

Ths integration sends a notification every time a deployment is @@ -1853,78 +818,6 @@ key = NAGIOS_BOT_API_KEY the test-post-receive branch.

-
- -

First, create the stream you'd like to use for Pagerduty notifications, - and subscribe all interested parties to this stream. We recommend the - stream name pagerduty. Keep in mind you still need to create - the stream first even if you are using this recommendation.

- -

Next, in Pagerduty, select Services under Configuration on the top - of the page.

- - -

Now navigate to the service you want to integrate with Zulip. From - there, click "Add a webhook". Fill in the form like this:

-
    -
  • Name: Zulip
    • -
  • Endpoint URL: {{ external_api_uri_subdomain }}/v1/external/pagerduty?api_key=abcdefgh&stream=pagerduty
    • -
- - - -
- -
- -

- Zulip supports integration with Papertrail as a - Webhook - that fires upon finding a certain log. To do this: -

- -

- First, create the stream you'd like to use for Papertrail - notifications, and subscribe all interested parties to this stream. We - recommend the stream name be papertrail. After create a bot named - Papertrail and note the API key. -

- -

- Next, log into your Papertrail Account and browse through your logs. - Search for logs you want to get alerts for and press the Save Search - to open up a modal window, then fill out the details and press the - Save & Setup an alert button. -

- - - - - -

- Go to the Create an alert section, press the Webhooks - link and place the below URL into the Webhook URL section. Be sure to set - the frequency to either minute, hour or day. -

- -

{{ external_api_uri_subdomain }}/v1/external/papertrail?api_key=abcdefgh&stream=papertrail

- - - -

- Note: api_key is the API key of your Zulip bot, - and stream is the stream name you want the - notifications sent to. -

- -

- Congratulations! You're done!
Your Papertrail notifications will - appear in Zulip: -

- - -
-
@@ -1972,8 +865,6 @@ key = NAGIOS_BOT_API_KEY
- -
@@ -1989,66 +880,6 @@ key = NAGIOS_BOT_API_KEY
-
- -

Zulip supports integration with Pingdom and can notify you of - uptime status changes from your Pingdom dashboard.

- -

First, create the stream you'd like to use for Pingdom notifications, - and subscribe all interested parties to this stream. We - recommend the name pingdom.

- -

{{ external_api_uri_subdomain }}/v1/external/pingdom?api_key=abcdefgh&stream=pingdom

- -

where api_key is the API key of your Zulip bot, - and stream is the stream name you want the - notifications sent to.

- -

Next, under following url:

-

https://my.pingdom.com/reports/integration/settings

-

create your integration by clicking on Add Integration button and filling form as following:

- - -

Last, during creating or editing your check, scroll down to Connect Integrations - section and ensure your integration is checked

- -

Congratulations! You're done!
Example Zulip notification - looks like this:

- - - -
- - -
- - -

Zulip supports integration with Pivotal Tracker and can notify you of changes - to the stories in your Pivotal Tracker project.

- -

First, create the stream you'd like to use for Pivotal Tracker - notifications, and subscribe all interested parties to this stream. We - recommend the name pivotal.

- -

Next, in the Settings page for your project, choose the Integrations - tab. Scroll down to the Activity Web Hook section, and enter - the following url:

- -

{{ external_api_uri_subdomain }}/v1/external/pivotal?api_key=abcdefgh&stream=pivotal

- -

where api_key is the API key of your Zulip bot, - and stream is the stream name you want the - notifications sent to.

- -

Choose version 5 of the API. Zulip supports both version 3 and version 5, but - version 5 contains more information that lets Zulip format more useful messages.

- - - -

Congratulations! You're done!
When you make changes in Pivotal Tracker they will be reflected in Zulip:

- -
-

Zulip supports Puppet integration and can notify you when Puppet runs fail (or when they happen at all).

@@ -2137,7 +968,6 @@ key = NAGIOS_BOT_API_KEY
-

RSS

@@ -2165,245 +995,6 @@ key = NAGIOS_BOT_API_KEY
- -
-

Semaphore

- -

See build and deploy statuses on Semaphore right in Zulip with the Zulip - Semaphore plugin!

- -

First, create the stream you'd like to use for Semaphore notifications, and - subscribe all interested parties to this stream. We recommend the - name builds.

- -

Next, on your {{ settings_html|safe }}, create a Semaphore bot.

- -

Then, log into your account on semaphoreci.com, and:

- -
    -
  1. -

    Visit the "Project Settings" page for the project for which you'd like to generate - Zulip notifications. Click the "Notifications" tab in the left sidebar, - click on "Webhooks" in the resulting menu, and then click on "+ Add Webhook".

    - - -
    2. -
  2. -

    You should now see a form that looks like this:

    - -

    - -

    Enter the following webhook URI, replacing the bot email address, - bot API key, and Zulip stream with the appropriate - information. Note: the @-sign in the bot e-mail - address must be escaped to %40:

    - -

    {{ external_uri_scheme }}semaphore-bot%40example.com:api_key@{{ external_api_path_subdomain }}/v1/external/semaphore?stream=builds

    -
    3. -
- -

Congratulations! You're done!
When you push to Semaphore, the - team can see these updates in real time in Zulip:

- - -
- -
-

Zulip supports integration with Sentry and can notify you of - issues that occurred in your project.

- -

First, create the stream you'd like to use for Sentry notifications, - and subscribe all interested parties to this stream. We - recommend the name sentry. Then, construct - the Sentry webhook URL as follows:

- -

{{ external_api_uri_subdomain }}/v1/external/sentry?api_key=abcdefgh&stream=sentry

- -

where api_key is the API key of your Zulip bot, - and stream is the stream name you want the - notifications sent to.

- -

Next, from Sentry dashboard choose your project.

-

-

From the menu on the right, choose Settings

-
-

On the settings page, from the menu on the left, choose Notifications
- In the Inactive Integrations section, choose WEBHOOKS

-
-

In the WebHooks box, insert the above webhook - URL into the Callback URLs* field.

-
-

And click Save changes

- -

Congratulations! You're done!
You will receive Zulip notifications - like this whenever a new Sentry alert is triggered:

- - -
- -
- -

- First, create the stream you'd like to use for Solano Labs CI Build notifications, and - subscribe all interested parties to this stream. The integration will use the default - stream solano labs if no stream is supplied in the hook; you still need - to create the stream even if you are using this default. -

- -

- Next, setup a bot that you would like to use with this integration. You will need its - API key. -

- -

- Next, follow - these instructions for Outgoing Web Hooks to configure a webhook for your Solano - Labs Organization and choose the repositories that should trigger a webhook a notification. -

- -

Enter a url of the following format into the URL field:

- -

{{ external_api_uri_subdomain }}/v1/external/solano?api_key=abcdefgh&stream=solano_labs

- -

Where abcdefgh should be replaced with the API key of the bot you - created earlier.

- -

Leave the Username and Password fields blank and click Add Web Hook

-

Congratulations! You're Done!

- -

Your messages will look like this:

- - - -
- -
-

Stash

- -

See what the team is committing to Stash right in Zulip with the Zulip - Stash plugin!

- -

First, create the stream you'd like to use for Stash notifications, and - subscribe all interested parties to this stream. We recommend the - name commits.

- -

Next, on your {{ settings_html|safe }}, create a Stash bot.

- -

Then:

- -
    -
  1. -

    Visit the Settings page for the Project that you'd like to generate - Zulip notifications. Click the "Hooks" option in the left sidebar, and - click "Add Hook" on the resulting page. Click the "Search for hook - plugins" link:

    - - -
    2. -
  2. -

    On the search results page, look for and install the "Post-Receive - WebHook for Stash" plugin:

    - - -
    3. -
  3. -

    Return to the Settings page for this Project and click the "Hooks" - option in the left sidebar. The newly-installed post-receive webhook - plugin is now listed in the "Post-receive" hooks section. Click the - edit icon next to the hook to configure it:

    - - -
    4. -
  4. -

    Supply the following webhook URL, replacing the bot email address, - bot API key, and Zulip stream with the appropriate - information. Note: the @-sign in the bot e-mail - address must be escaped to %40:

    - -

    {{ external_uri_scheme }}stash-bot%40example.com:api_key@{{ external_api_path_subdomain }}/v1/external/stash?stream=commits

    - - -
    5. -
- -

Congratulations! You're done!
When you push to Stash, the - team can see these updates in real time in Zulip:

- - -
- -
- -

- You can choose to be notified whenever certain events are triggered on Stripe - by adding a webhook to your Stripe account. First, create a stream where the events - are to be sent. -

- -

Next, on your {{ settings_html|safe }}, create a Stripe bot.

- -

- Add a webhook to your Stripe account by going to "Your account"->"Account - settings"->"Webhooks"->"Add Endpoint" and adding the following URL, - replacing the bot email address (with the @sign escaped to %40), - bot API key, Zulip stream, and Zulip topic with the appropriate values: -

- -

e.g.

- -
    -
  • sales-bot%40example.com instead of stripe-bot%40example.com
    • -
  • abcdef0123 instead of api_key
    • -
  • finance instead of sales
    • -
  • transactions instead of Stripe
    • -
- {{ external_uri_scheme }}stripe-bot%40example.com:api_key@{{ external_api_path_subdomain }}/v1/external/stripe?stream=sales%26topic=Stripe - -

- {%if 'http:' in external_uri_scheme %} - Note that Stripe will only accept https webhooks! - {%endif%} -

- - - -

- To set up different topics for different events, create separate webhooks - for those events, customizing the URL stream and topic for each. -

- - - -

- Congratulations! -

- -

- You will now receive notifications for the events you have chosen. - Zulip currently supports the following events: -

- -
    -
  • Charge Dispute Closed
    • -
  • Charge Dispute Created
    • -
  • Charge Failed
    • -
  • Charge Succeeded
    • -
  • Customer Created
    • -
  • Customer Deleted
    • -
  • Customer Subscription Created
    • -
  • Customer Subsciption Deleted
    • -
  • Customer Subscription Trial Will End
    • -
  • Invoice Payment Failed
    • -
  • Order Payment Failed
    • -
  • Order Payment Succeeded
    • -
  • Order Updated
    • -
  • Transfer Failed
    • -
  • Transfer Paid
    • -
- - -
-
@@ -2453,136 +1044,6 @@ key = NAGIOS_BOT_API_KEY
-
- -

Go on your {{ settings_html|safe }}, create a Taiga bot. - Please note the bot name and API key.

- -

Since Taiga allows you to integrate services on a per - project basis, you have to perform the following steps - for every project that you want to send - notifications to Zulip.

- -
    -
  1. -

    Go to Admin > Integration > Webhooks menu.

    -
    2. -
  2. -

    Click Add a new webhook.

    -
    3. -
  3. -

    Fill out the form by following the instructions: -

      -
    • - Name - to recognize this service, preferably Zulip -
      • -
    • - URL - - 
      -{{ external_api_uri_subdomain }}/v1/external/taiga?stream=STREAM_NAME&topic=TOPIC_NAME&api_key=BOT_API_KEY
      -
        -
      • STREAM_NAME - The url-encoded name of - stream which you want to receive notifications. - You can use an existing Zulip stream or create a - new one for this. -
        • -
      • TOPIC_NAME - The url-encoded - topic where your Taiga notifications will be - posted. (Read the notes below.)
        • -
      • BOT_API_KEY - API key created in Zulip.
        • -
      -

      Remember to url-encode the stream and topic - names. E.g. spaces need to be replaced - with %20 (e.g. so if you want your stream - to be called "My awesome project", STREAM_NAME - should be My%20awesome%20project).

      -
      • -
    • - Secret key - once again the API key created in Zulip. -
      • -
    -

    -
    4. -
  4. -

    Click Save once you've finished filling out the form.

    -
    5. -
-

That's it! Your actions on Taiga should now cause - notifications on the Zulip stream you specified above. -

- - There are two different ways you may want to consider - when organizing your Taiga - Zulip integration:

-
    -
  • - Use special Zulip stream for Taiga messages - name - it Taiga. (Make sure to create this stream - first!) For every integrated project, provide a new topic. - 
    -STREAM_NAME = Taiga
-TOPIC = Project
    -
    • -
  • - If you already have a Zulip stream for managing a project, - you can also use this existing stream and add Taiga - notifications using special topic.(Remember about - substituting spaces with %20).
    -STREAM_NAME = My%20existing%20Zulip%20stream
-TOPIC = Taiga
    -
    • -
- -
- -
- -

See your Teamcity build status in Zulip!

- -

First, create the stream you'd like to use for Teamcity - notifications, and subscribe all interested parties to this stream. We - recommend the name teamcity.

- -

Next, set up a bot for the integration. You'll need the bot's API key - to construct a URL for Teamcity.

- -

Next, install the tcWebHooks plugin - onto your Teamcity server. Follow the plugin instructions in your - Teamcity documentation, or refer to - the online Teamcity documentation.

- -

Next, in your Teamcity project overview page, - click the "Webhooks" tab, and add a new project webhook. - Enter the following URL:

- -

{{ external_api_uri_subdomain }}/v1/external/teamcity?api_key=abcdefgh&stream=teamcity

- -

where api_key is the API key of your Zulip bot, - and stream is the stream name you want the - notifications sent to.

- -

Uncheck all "Trigger on Events" options, and check - "Trigger when build is Successful" and "Trigger when build Fails". - Optionally, check "Only trigger when build changes from Failure to Success" - and "Only trigger when build changes from Success to Failure".

- -

Set the Payload Format to "JSON" and save your webhook.

- - - -

Congratulations! You're done!
Your Teamcity build - notifications will appear in Zulip:

- - -

Personal Builds
When a user runs a personal build, if Zulip can - map their Teamcity username to a Zulip user, that Zulip user will receive a - private message with the result of their personal build.

- - - -
- -
@@ -2634,139 +1095,6 @@ TOPIC = Taiga in zulip_trac_config.py.

-
- -

First, create the stream you'd like to use for Transifex - notifications, and subscribe all interested parties to this stream. We - recommend the name transifex.

- -

Next, set up a bot for the integration. You'll need the bot's API key - to construct a URL for Transifex.

- -

{{ external_api_uri_subdomain }}/v1/external/transifex?api_key=abcdefgh&stream=transifex

- -

where api_key is the API key of your Zulip bot, - and stream is the stream name you want the - notifications sent to.

- -

Next, in Transifex, go to your project settings page: - Project Details → Manage → Edit Project and scroll down to - WEB HOOK URL. Paste the URL you constructed into the box and - save your changes.

- -

Congratulations! You're done!
- Example message: -

- - - -
- -
- -

See your Travis CI build notifications in Zulip!

- -

First, create the stream you'd like to use for notifications, and subscribe - all interested parties to this stream. We recommend the name travis.

- -

Next, set up a bot for the integration. You'll need the bot's API key - to construct a URL for Travis CI.

- -

Finally, set up a webhook in your .travis.yml file:

- -
-notifications:
-  webhooks:
-    - {{ external_api_uri_subdomain }}/v1/external/travis?stream=travis&topic=build-status&api_key=abcdefgh
-
- -

Congratulations! You're done!
When a code build occurs, - you're receive a notification on the specified stream and topic.

- - -
- -
-

This webhook integration for Trello is the recommended way to - integrate with Trello, and should support all the features of - the legacy Trello cron-based - integration.

- -

- First, create the stream you'd like to use for Trello notifications, - and subscribe all interested parties to this stream. We recommend the - name trello. -

- -

- Your webhook URL is:
- {{ external_api_uri_subdomain }}/v1/external/trello?api_key=abcdefgh&stream=trello
- where api_key is the API key of your Zulip bot, - and stream is the stream name you want the notifications sent to. -

- -

- Before you create a webhook, - you'll need to follow the steps below to get an APPLICATION_KEY, and a UserToken, - and to fetch the board's idModel. -

- -

- To generate the APPLICATION_KEY, open this URL in your web browser:
- https://trello.com/1/appkey/generate. -

- -

- To generate a read access token, fill in and open this URL in the browser while logged into your Trello account: - https://trello.com/1/authorize?key=<APPLICATION_KEY>&name=Issue+Manager&expiration=never&response_type=token&scope=read
- You will receive your UserToken. Note it. -

- -

- Within the the board URL, you can find the TRELLO_BOARD_SHORT_ID. - The Trello URL format is:
- https://trello.com/b/TRELLO_BOARD_SHORT_ID/boardName. -

- -

- Now you have the APPLICATION_KEY, UserToken and TRELLO_BOARD_SHORT_ID.
- Construct this URL and open it in your web browser:
- https://api.trello.com/1/board/<TRELLO_BOARD_SHORT_ID>?key=<APPLICATION_KEY>&token=<UserToken>
- You'll receive some JSON. Within that, find the id value. That's your idModel; note it. -

- -

- Now you have the ingredients to create your webhook. - Send a POST request to this URL with this data: - https://api.trello.com/1/tokens/<UserToken>/webhooks/?key=<APPLICATION_KEY> -

{
-  "description": "Webhook for Zulip integration",
-  "callbackURL": "<URL_TO_ZULIP_WEBHOOK_FROM_SECOND_STEP>",
-  "idModel": "<ID_MODEL>",
-}
- You can use curl to do this:
-
curl 'https://api.trello.com/1/tokens/<UserToken>/webhooks/?key=<APPLICATION_KEY>'
--H 'Content-Type: application/json' -H 'Accept: application/json'
---data-binary $'{\n  "description": "Webhook for Zulip integration",\n  "callbackURL": "<URL_TO_ZULIP_WEBHOOK_FROM_SECOND_STEP>",\n  "idModel": "<ID_MODEL>"\n}'
---compressed
- The response from Trello should look like:
-
{
-  "id": "<WEBHOOK_ID>",
-  "description": "Webhook for Zulip integration",
-  "idModel": "<ID_MODEL>",
-  "callbackURL": "<URL_TO_ZULIP_WEBHOOK_FROM_SECOND_STEP>",
-  "active": true
-}
- Congratulations! You've created a webhook and your integration is live. -

- -

- When you make changes in on this board in Trello, you will - receive Zulip notifications like this: -

-

-
-

This legacy integration for Trello works by running a script @@ -2881,179 +1209,6 @@ access_token_secret =

-
- - -

See Updown reports in Zulip! This is great to be up to date with - downtime in the services you monitor with Updown! -

- -

First, create the stream you'd like to use for updown - notifications, and subscribe all interested parties to this - stream. We recommend the name updown.

- -

Go to your Updown - settings page and in WEBHOOKS section, enter - the following as the URL:

- -

{{ external_api_uri_subdomain }}/v1/external/updown?api_key=abcdefgh&stream=updown

- - -

Congratulations! You're done!
- Now you'll receive Updown notifications for your service in Zulip. -

- - - -
- -
- -

See your Yo App notifications in Zulip!

- -

Go to your Zulip settings and set up a Zulip bot for the - integration. You'll need the bot's API key to construct a URL for - Yo App Callback.

- -

You will receive your notifications as a private message between you and the bot.

- -

Create a URL using your bot's API key and the email address associated with your Zulip account:

- - 


-{{ external_api_uri_subdomain }}/api/v1/external/yo?email=awesome@zulip.example.com&api_key=abcdefgh
-

- -

Copy the URL created and go to yoapi.justyo.co.

-

Sign in using your username and password and go to Edit Profile.

- - - -

Paste the URL in the Callback field and click on Update.

- -

Congratulations! You're done!
When someone sends your username a Yo, - you'll receive a notification as a private message from the bot - like this:

- - - -

Multiple users can use the same Yo bot; each user should use - their own Zulip account email in the webhook URL.

-
- -
-

Get notifications from every event supported by Zapier.

-

First, create the stream you'd like to use for Zapier notifications, - and subscribe all interested parties to this stream.

- -

{{ external_api_uri_subdomain }}/v1/external/zapier?api_key=abcdefgh&stream=zapier

- -

- Next, create a ZAP, picking the service you'd like - to receive notifications from as Trigger (Step 1) -

- - -

and Webhook as Action (Step 2).

- - -

As Step 2 action please choose POST

- - -

- Configure Set up Webhooks by Zapier POST as follows: - -

    -
  • URL is the url we created above
    • -
  • Payload Type set to JSON
    • -
-

- -

- Finally, configure Data. - You have to add 2 fields: -

    -
  • subject is field corresponding to a subject of the message
    • -
  • content is field corresponding to a content of the message
    • -
-

- -

Example configuration:

- - -

You're done! Example message:

- - -
- -
-

First, create the stream you'd like to use for Zendesk notifications, - and subscribe all interested parties to this stream. We recommend the - stream name zendesk. Keep in mind you still need to create - the stream first even if you are using this recommendation.

- -

Next, in Zendesk, open your Admin view via gear in the bottom-left - corner. In the Admin view, click on Extensions, then click "add - target".

- - - -

From there, click "URL target". Fill in the form like this:

-
    -
  • Title: Zulip
    • -
  • URL: {{ external_api_uri_subdomain }}{% raw %}/v1/external/zendesk?ticket_title={{ticket.title}}&ticket_id={{ticket.id}}&stream=zendesk{% endraw %}
    • -
  • Method: POST
    • -
  • Attribute Name: message
    • -
  • Username: your bot's user name, e.g. zendesk-bot@yourdomain.com
    • -
  • Password: your bot's API key
    • -
- - - -

Now select "Test Target" and click Submit. A test message should - appear in the zendesk stream. If the message was received, save the - target by selecting "Create target" and clicking Submit.

- -

From here, add a new trigger. You'll do this for every action you want - to create a Zulip notification. Triggers are added by selecting Triggers - in the left menu and then clicking "add trigger" in the top right.

- - - -

Let's say you want a notification each time a ticket is updated. Put - in a descriptive title like "Announce ticket update". Under "Meet all of - the folllowing conditions" select "Ticket: is..." and then select - Updated. In the "Perform these actions" section select "Notification: - Notify target" then select Zulip.

- -

Next we need need to enter the message body into Message. You can use - Zulip markdown and the Zendesk placeholders when creating your message. - You can copy this example template:

- {% raw %} - 
Ticket [#{{ticket.id}}: {{ticket.title}}]({{ticket.link}}), was updated by {{current_user.name}}
-
-* Status: {{ticket.status}}
-* Priority: {{ticket.priority}}
-* Type: {{ticket.ticket_type}}
-* Assignee: {{ticket.assignee.name}}
-* Tags: {{ticket.tags}}
-* Description:
-``` quote
-{{ticket.description}}
-```
- {% endraw %} - - - -

Finally, click Submit.

- -

Congratulations! You're Done!
When a ticket is updated - you will see a notification like the following, to the stream - zendesk, with a topic that matches the ticket's subject - name:

- - -
-
{% endblock %} diff --git a/tools/check-templates b/tools/check-templates index 846289a0c3..23ad2ab77b 100755 --- a/tools/check-templates +++ b/tools/check-templates @@ -134,6 +134,11 @@ def check_html_templates(templates, modified_only, all_dups): 'templates/zerver/register.html', 'templates/zerver/right-sidebar.html', 'templates/zerver/search_operators.html', + + 'zerver/webhooks/deskdotcom/doc.html', + 'zerver/webhooks/freshdesk/doc.html', + 'zerver/webhooks/taiga/doc.html', + 'zerver/webhooks/zendesk/doc.html', ] validate(fn=fn, check_indent=(fn not in bad_files)) diff --git a/zerver/lib/integrations.py b/zerver/lib/integrations.py index 06a7600a85..a39e4e566e 100644 --- a/zerver/lib/integrations.py +++ b/zerver/lib/integrations.py @@ -24,11 +24,12 @@ features for writing and configuring integrations efficiently. class Integration(object): DEFAULT_LOGO_STATIC_PATH = 'static/images/integrations/logos/{name}.png' - def __init__(self, name, client_name, logo=None, secondary_line_text=None, display_name=None): - # type: (str, str, Optional[str], Optional[str], Optional[str]) -> None + def __init__(self, name, client_name, logo=None, secondary_line_text=None, display_name=None, doc=None): + # type: (str, str, Optional[str], Optional[str], Optional[str], Optional[str]) -> None self.name = name self.client_name = client_name self.secondary_line_text = secondary_line_text + self.doc = doc if logo is None: logo = self.DEFAULT_LOGO_STATIC_PATH.format(name=name) @@ -51,10 +52,11 @@ class WebhookIntegration(Integration): DEFAULT_FUNCTION_PATH = 'zerver.webhooks.{name}.view.api_{name}_webhook' DEFAULT_URL = 'api/v1/external/{name}' DEFAULT_CLIENT_NAME = 'Zulip{name}Webhook' + DEFAULT_DOC_PATH = '{name}/doc.html' def __init__(self, name, client_name=None, logo=None, secondary_line_text=None, - function=None, url=None, display_name=None): - # type: (str, Optional[str], Optional[str], Optional[str], Optional[str], Optional[str], Optional[str]) -> None + function=None, url=None, display_name=None, doc=None): + # type: (str, Optional[str], Optional[str], Optional[str], Optional[str], Optional[str], Optional[str], Optional[str]) -> None if client_name is None: client_name = self.DEFAULT_CLIENT_NAME.format(name=name.title()) super(WebhookIntegration, self).__init__(name, client_name, logo, secondary_line_text, display_name) @@ -71,6 +73,10 @@ class WebhookIntegration(Integration): url = self.DEFAULT_URL.format(name=name) self.url = url + if doc is None: + doc = self.DEFAULT_DOC_PATH.format(name=name) + self.doc = doc + @property def url_object(self): # type: () -> LocaleRegexProvider diff --git a/zerver/lib/test_helpers.py b/zerver/lib/test_helpers.py index 573f1b2714..8f452ac43f 100644 --- a/zerver/lib/test_helpers.py +++ b/zerver/lib/test_helpers.py @@ -395,10 +395,11 @@ def get_all_templates(): def is_valid_template(p, n): # type: (Text, Text) -> bool - return (not n.startswith('.') and - not n.startswith('__init__') and - not n.endswith(".md") and - isfile(p)) + return 'webhooks' not in p \ + and not n.startswith('.') \ + and not n.startswith('__init__') \ + and not n.endswith('.md') \ + and isfile(p) def process(template_dir, dirname, fnames): # type: (str, str, Iterable[str]) -> None diff --git a/zerver/webhooks/airbrake/doc.html b/zerver/webhooks/airbrake/doc.html new file mode 100644 index 0000000000..8048194a26 --- /dev/null +++ b/zerver/webhooks/airbrake/doc.html @@ -0,0 +1,26 @@ +

Get Zulip notifications for your Airbrake bug tracker!

+ +

+ First, create the stream you'd like to use for Airbrake notifications, and + subscribe all interested parties to this stream. We recommend the + name airbrake. +

+ +

+ Next, on your {{ settings_html|safe }}, create an Airbrake bot. Construct the URL for + the Airbrake bot using the API key and stream name: + {{ external_api_uri_subdomain }}/v1/external/airbrake?api_key=abcdefgh&stream=airbrake +

+ +

+ Now, go to your project's settings on the Airbrake site. Click + on the Integration section. + Choose Webhook, provide the above URL, + check Enabled, and save. Your Webhook + configuration should look similar to: +

+ + +

Congratulations! You're done!
Your messages may look like:

+ + diff --git a/zerver/webhooks/appfollow/doc.html b/zerver/webhooks/appfollow/doc.html new file mode 100644 index 0000000000..829a7f6937 --- /dev/null +++ b/zerver/webhooks/appfollow/doc.html @@ -0,0 +1,40 @@ +

+ Receive user reviews from your tracked apps on AppFolllow in Zulip + using the Zulip AppFollow plugin! +

+ +

+ First, create the stream you'd like to use for AppFollow notifications, and + subscribe all interested parties to this stream. We recommend the + name appfollow. +

+ +

Next, on your {{ settings_html|safe }}, create an AppFollow bot.

+ +

Then, log into your account on appfollow.io, and:

+ +
    +
  1. +

    + Click on the app for which you'd like to receive reviews. + Click on Integrations and then go to the Others tab. +

    + + +
    2. +
  2. +

    + In the Webhook URL field, enter the following URL, replacing the bot API key + and Zulip stream with the appropriate information. +

    + +

    {{ external_api_uri_subdomain }}/v1/external/appfollow?api_key=test_api_key&stream=appfollow

    +
    3. +
+ +

+ Save changes – all done!
+ New reviews for your app will be delivered to your Zulip stream. +

+ + diff --git a/zerver/webhooks/beanstalk/doc.html b/zerver/webhooks/beanstalk/doc.html new file mode 100644 index 0000000000..920e7b9961 --- /dev/null +++ b/zerver/webhooks/beanstalk/doc.html @@ -0,0 +1,27 @@ +

Zulip supports both SVN and Git notifications from Beanstalk.

+ +

+ First, create the stream commits and subscribe all + interested parties to this stream. +

+ +

+ Next, in the Beanstalk web application, go to the Setup page and choose the Integrations tab. + Choose the Webhooks integration from the list presented. + Make sure to replace the @ in the + bot's email address with %40, + as Beanstalk's website will incorrectly refuse to parse a username containing a @. +

+ +

+ In the URL field, enter + {{ external_uri_scheme }}bot_email:bot_api_key@{{ external_api_path_subdomain }}/v1/external/beanstalk: +

+ + +

+ Congratulations! You're done!
Whenever you do a + deployment, you'll get an automated notification that looks like + this: +

+ diff --git a/zerver/webhooks/bitbucket/doc.html b/zerver/webhooks/bitbucket/doc.html new file mode 100644 index 0000000000..77573b825a --- /dev/null +++ b/zerver/webhooks/bitbucket/doc.html @@ -0,0 +1,39 @@ +

+ Zulip supports both Git and Mercurial notifications from + Bitbucket. This integration is for the old-style Bitbucket + webhooks used by Bitbucket Enterprise. +

+ +

+ First, create the stream you'd like to use for Bitbucket notifications, + and subscribe all interested parties to this stream. The integration will + use the default stream commits if no stream is supplied in the + hook; you still need to create the stream even if you are using this + default. +

+ +

+ Next, from your repository's web page, go to the Administration page and choose Hooks on the left-hand side. + Choose the POST hook from the list presented and click "Add hook." Make sure to replace the + @ in the bot's email address with %40, + as Bitbucket will not execute the hook if the username contains a @. +

+ +

+ In the URL field, enter + {{ external_uri_scheme }}bot_email:bot_api_key@{{ external_api_path_subdomain }}/v1/external/bitbucket: +

+ + +

+ By default, notifications are sent to the commits stream. + To send notifications to a different stream, + append ?stream=stream_name to + the URL. +

+ +

+ Congratulations! You're done!
Whenever you push code to your repository, + you'll get an automated notification that looks like this: +

+ diff --git a/zerver/webhooks/bitbucket2/doc.html b/zerver/webhooks/bitbucket2/doc.html new file mode 100644 index 0000000000..dfb00edbfe --- /dev/null +++ b/zerver/webhooks/bitbucket2/doc.html @@ -0,0 +1,34 @@ +

+ Zulip supports both Git and Mercurial notifications from + Bitbucket. This integration is for the new-style Bitbucket + webhooks used by the Bitbucket SAAS service. +

+ +

+ First, create the stream you'd like to use for Bitbucket notifications, + and subscribe all interested parties to this stream. The integration will + use the default stream bitbucket if no stream is supplied in the + hook; you still need to create the stream even if you are using this + default. +

+ +

The URL you create will be in the following format:

+

{{ external_api_uri_subdomain }}/v1/external/bitbucket2?api_key=abcdefgh&stream=bitbucket

+ +

+ where api_key is the API key of your Zulip bot, + and stream is the stream name you want the + notifications sent to. +

+ +

+ Next, from your repository's web page, go to the Settings page and choose Webhooks on the left-hand side. + Click Add webhook, set URL to the URL you created above. Remember to click the 'active' checkbox. + Click Save. +

+ +

+ Congratulations! You're done!
+ Example message: +

+ diff --git a/zerver/webhooks/circleci/doc.html b/zerver/webhooks/circleci/doc.html new file mode 100644 index 0000000000..3160d2e468 --- /dev/null +++ b/zerver/webhooks/circleci/doc.html @@ -0,0 +1,30 @@ +

+ Zulip supports integration with CircleCI and can notify you of + your build statuses. +

+ +

+ First, create the stream you'd like to use for CircleCI notifications, + and subscribe all interested parties to this stream. We + recommend the name circleci. +

+ +

{{ external_api_uri_subdomain }}/v1/external/circleci?api_key=abcdefgh&stream=circleci

+ +

+ where api_key is the API key of your Zulip bot, + and stream is the stream name you want the + notifications sent to. +

+ +

+ Next, modify your circle.yml as described + here. +

+ +

+ Congratulations! You're done!
When a build is done, + you'll get a notification like this: +

+ + diff --git a/zerver/webhooks/codeship/doc.html b/zerver/webhooks/codeship/doc.html new file mode 100644 index 0000000000..e79bc87780 --- /dev/null +++ b/zerver/webhooks/codeship/doc.html @@ -0,0 +1,34 @@ +

+ Zulip supports integration with Codeship and can notify you of + your build statuses. +

+ +

+ First, create the stream you'd like to use for Codeship notifications, + and subscribe all interested parties to this stream. We + recommend the name codeship. +

+ +

{{ external_api_uri_subdomain }}/v1/external/codeship?api_key=abcdefgh&stream=codeship

+ +

+ where api_key is the API key of your Zulip bot, + and stream is the stream name you want the + notifications sent to. +

+ +

+ Next, go to your project settings - notification settings + page. The url should look like the following: +

+

https://codeship.com/projects/PROJECT_ID/configure_notifications

+

where PROJECT_ID is the id of your project in Codeship.

+

Scroll to the Webhook section and fill out the form as follows:

+ + +

+ Congratulations! You're done!
When a build is + triggered, you'll get a notification like this: +

+ + diff --git a/zerver/webhooks/crashlytics/doc.html b/zerver/webhooks/crashlytics/doc.html new file mode 100644 index 0000000000..c995c2b600 --- /dev/null +++ b/zerver/webhooks/crashlytics/doc.html @@ -0,0 +1,30 @@ +

+ Zulip supports integration with Crashlytics and can notify you + about Crashlytics issues. +

+ +

+ First, create the stream you'd like to use for Crashlytics notifications, + and subscribe all interested parties to this stream. We + recommend the name crashlytics. +

+ +

{{ external_api_uri_subdomain }}/v1/external/crashlytics?api_key=abcdefgh&stream=crashlytics

+ +

+ where api_key is the API key of your Zulip bot, + and stream is the stream name you want the + notifications sent to. +

+ +

+ Click on the app in + your Crashlytics settings panel. + Next, on the integrations subpage, click “Web Hook,” enter the URL we created above and click + Verify. +

+

+ Congratulations! You're done!
When an issue occurs, + you'll get a notification like this: +

+ diff --git a/zerver/webhooks/delighted/doc.html b/zerver/webhooks/delighted/doc.html new file mode 100644 index 0000000000..a002ccb5f3 --- /dev/null +++ b/zerver/webhooks/delighted/doc.html @@ -0,0 +1,35 @@ +

+ Zulip supports integration with Delighted and can notify you + about updates in feedback responses organized by Delighted. +

+ +

+ First, create the stream you'd like to use for Delighted notifications, + and subscribe all interested parties to this stream. We + recommend the name delighted. Next, create a bot named Delighted + and retrive the API key of the bot and place it into the API parameter in the URL below. +

+ +

{{ external_api_uri_subdomain }}/v1/external/delighted?api_key=abcdefgh&stream=delighted

+ +

+ Modify the parameters of the URL above, where api_key is the API key of your Zulip bot, + and stream is the stream name you want the + notifications sent to. +

+ +

+ Go to your Delighted Webhook Integration settings + panel. + Under Send webhook notifications for:: input the above URL with the modifications into + the URL textbox and press Save and turn on to finish. +

+ + + +

+ Congratulations! You're done!
When an issue occurs, + you'll get a notification like this: +

+ + diff --git a/zerver/webhooks/deskdotcom/doc.html b/zerver/webhooks/deskdotcom/doc.html new file mode 100644 index 0000000000..3918427adc --- /dev/null +++ b/zerver/webhooks/deskdotcom/doc.html @@ -0,0 +1,120 @@ +

+ First, create the stream you'd like to use for Desk.com notifications, + and subscribe all interested parties to this stream. We recommend the + stream name desk. Keep in mind you still need to + create the stream first even if you are using this recommendation. +

+ +

+ Next, in Desk.com, open your Admin view via the top-left corner + dropdown. In the Admin view, click on Apps, then click Install under + "Custom Action": +

+ + +

+ From there, click "Install Custom Action" and accept the terms. Fill + in the form like this: +

+ + + + +

+ Click Create to save your settings. From the next screen, click Add + Action add a new action. You'll do this for every action you want a + notification on Zulip for. (To add another action later, look for your + custom action on the Apps page under "Installed Apps." +

+ + + +

+ Let's say you want a notification each time a case is updated. Put + in a descriptive name like "Announce case update", select "POST a string to a URL" + for Action Type, and copy-paste this to the "Appended URL path": +

+{% raw %} +

?stream=desk&topic={{ case.id }}:+{{ case.subject }}

+{% endraw %} +

+ The "appended URL path" will be the same for every notification — + it makes sure the notification goes to the appropriate stream and topic + within Zulip. +

+ +

+ Next, copy this template Zulip message into "Message to + POST": +

+{% raw %} + 
+Case [{{ case.id }}, {{ case.subject }}]({{ case.direct_url }}), was updated.
+
+* Status: {{ case.status.name }}
+* Priority: {{ case.priority }}
+* Customer: {{ customer.name }}
+* Company: {{ customer.company }}
+* Description: {{ case.description }}
+
+

+ You don't need to edit that, although you may if you wish. All + the funny-looking stuff inside {{ and }} + will be filled in by Desk.com for each event. The dialog should look + like this: +

+{% endraw %} + + + +

+ Click Add Action to save, and then on the next screen click the slider + next to the action to enable it. This is important — actions are turned off + by default! +

+ + + +

+ Now you need to create a rule that triggers this action. Desk.com's + support center has a + lengthy + article on rules, but in short, click on "Cases" up at the top, + "Rules" on the left side, and then the specific event you want to notify + on — in our example, "Inbound Interaction". +

+ + + +

+ Select the types of interaction you want your rule to apply to, + such as Chat. Specify the name and click on "Add Rule." +

+ + + +

+ In the next screen, provide the details. First, click Add Actions to + display the rule actions. Select "Trigger an App Action" in the dropdown, and + then the name of the custom action you created earlier when the second + dropdown appears. You can add additional "All" or "Any" conditions if desired. + Also select when the rule should run (if not "Anytime") and enable it. +

+ + + +

Finally, click Update.

+ +

+ Congratulations! You're done!
When a case is updated, + you'll see a notification like the following, to the stream + desk, with a topic that matches the case's subject name: +

+ + diff --git a/zerver/webhooks/freshdesk/doc.html b/zerver/webhooks/freshdesk/doc.html new file mode 100644 index 0000000000..70be932e01 --- /dev/null +++ b/zerver/webhooks/freshdesk/doc.html @@ -0,0 +1,236 @@ +

Freshdesk

+ +

+ See customer support interactions right in Zulip, with our Freshdesk + integration! Note that this integration must be set up by an administrator + for your Freshdesk instance. +

+ +

+ First, create the stream you'd like to use for Freshdesk notifications, + and subscribe all interested parties to this stream. We recommend the + stream name freshdesk. +

+ +

Next, on your {{ settings_html|safe }}, create a Freshdesk bot.

+ +

+ Now we can set up the Freshdesk events that will trigger + Zulips. Freshdesk provides separate triggering mechanisms for ticket + creation and ticket changes, so we'll set up these triggers in two + parts. +

+ +

Part 1: Zulip notifications for new Freshdesk tickets

+ +
    +
  1. +

    + Visit your Freshdesk admin page. Under the "Helpdesk + Productivity" section, click the "Dispatch'r" icon: +

    + + + +

    + Click the "New rule" button to create a new Dispatch'r rule + that will send notifications to Zulip when Freshdesk tickets are + opened. +

    +
    2. +
  2. +

    + On the Dispatch'r rule creation page, give the rule a name and + description. Next, we need to specify the conditions under which to + trigger Zulip notifications. There isn't a shortcut for "always + generate a notification on ticket creation", so we'll instead fake it + by picking two complementary conditions: when the source is + email, and when the source is not email: +

    + + +
    3. +
  3. + +

    + In the "Action" section, add a new action of + type "Trigger Webhook". Set the "Request Type" + to "POST". Set the following "Callback URL", replacing + the Zulip stream with your desired stream: +

    + +

    + {{ external_api_uri_subdomain }}/v1/external/freshdesk?stream=freshdesk +

    + +

    + Check the "Requires Authentication" box, and supply the bot + e-mail address and API key. +

    + +

    The Action section should look like this so far:

    + + +
    4. +
  4. +

    + Select "JSON" for the "Encoding". Under the encoding, select + "Advanced". Paste the following JSON into the "Content" + box: +

    + + 
    {"freshdesk_webhook":
+{
+    "triggered_event":"{{triggered_event}}",
+    "ticket_id":"{{ticket.id}}",
+    "ticket_url":"{{ticket.url}}",
+    "ticket_type":"{{ticket.ticket_type}}",
+    "ticket_subject":"{{ticket.subject}}",
+    "ticket_description":"{{ticket.description}}",
+    "ticket_status":"{{ticket.status}}",
+    "ticket_priority":"{{ticket.priority}}",
+    "requester_name":"{{ticket.requester.name}}",
+    "requester_email":"{{ticket.requester.email}}",
+}
+}
+
    + +

    + These ticket details are what will be forwarded to Zulip. The + pasted JSON should look like this: +

    + + +
    5. +
  5. +

    + Save your new Dispatch'r rule. The next time a Freshdesk ticket is + opened, the team will get a notification in Zulip! +

    +
    6. +
+ +

+ If you only want to receive Zulip notifications on ticket creation, + stop here, you're done! If you also want notifications on important ticket + changes, please continue to the next section. +

+ +

Part 2: Zulip notifications on ticket changes

+ +
    +
  1. +

    + Visit your Freshdesk admin page. Under the "Helpdesk + Productivity" section, click the "Observer" icon: +

    + + + +

    + Click the "New rule" button to create a new Observer rule + that will send notifications to Zulip when Freshdesk tickets are + updated. +

    +
    2. +
  2. +

    + On the Observer rule creation page, give the rule a name and + description. Under "When Any Of These Events Occur", create + these new rules: +

    +
      +

    • Priority is changed, from Any Priority, to Any Priority

      • +

    • Status is changed, from Any Status, to Any Status

      • +

    • Note is added, Type Any

      • +
    + +

    + If you do not want to receive Zulip notifications on one or more of + these events, leave out the rule for that event. +

    + +

    + Under "And The Events Are Performed By", + select "Anyone". +

    + +

    So far, the rule should look like this:

    + + +
    3. +
  3. +

    + Next, we need to specify the types of tickets that will trigger + Zulip notifications. There isn't a shortcut for "always generate a + notification on ticket update", so as before we'll instead fake it by + picking two complementary conditions: when the source is email, + and when the source is not email: +

    + + +
    4. +
  4. +

    + Under "Perform These Actions", add a new action of + type "Trigger Webhook". Set the "Request Type" + to "POST". Set the following "Callback URL", replacing + the Zulip stream with your desired stream: +

    + +

    + {{ external_api_uri_subdomain }}/v1/external/freshdesk?stream=freshdesk +

    + +

    + Check the "Requires Authentication" box, and supply the bot + e-mail address and API key. +

    + +

    The Action section should look like this so far:

    + + +
    5. +
  5. +

    + Select "JSON" for the "Encoding". Under the encoding, + select "Advanced". Paste the following JSON into + the "Content" box: +

    + + 
    +{"freshdesk_webhook":
+    {
+        "triggered_event":"{{triggered_event}}",
+        "ticket_id":"{{ticket.id}}",
+        "ticket_url":"{{ticket.url}}",
+        "ticket_type":"{{ticket.ticket_type}}",
+        "ticket_subject":"{{ticket.subject}}",
+        "ticket_description":"{{ticket.description}}",
+        "ticket_status":"{{ticket.status}}",
+        "ticket_priority":"{{ticket.priority}}",
+        "requester_name":"{{ticket.requester.name}}",
+        "requester_email":"{{ticket.requester.email}}",
+    }
+}
    +

    + These ticket details are what will be forwarded to Zulip. The + pasted JSON should look like this: +

    + + +
    6. +
  6. +

    + Save your new Observer rule. The next time a Freshdesk ticket is + updated, the team will get a notification in Zulip! +

    +
    7. +
+ +

+ Congratulations! You're done!
You'll now see support + progress in real time in Zulip: +

+ + diff --git a/zerver/webhooks/github/doc.html b/zerver/webhooks/github/doc.html new file mode 100644 index 0000000000..aea5fef7c6 --- /dev/null +++ b/zerver/webhooks/github/doc.html @@ -0,0 +1,53 @@ +

+ This webhook bases on deprecated concept that is + GitHub Services +

+ +

+ First, create the stream you'd like to use for GitHub notifications, + and subscribe all interested parties to this stream. The integration will + use the default stream commits if no stream is supplied in + the hook; you still need to create the stream even if you are using this + default. +

+ +

Next, go to your repository page and click "Settings":

+

+ +

From there, select "Webhooks & Services":

+

+ +

To find the Zulip hook, you have to click on Configure services.

+

+ +

+ Select "Zulip" from the list of service hooks. Fill in + the API key and email address for your bot and check + the "active" checkbox. Specify + {{ external_api_uri_subdomain }}/v1/external/github as the "Alternative + endpoint". You can optionally supply the Zulip stream (the + default is commits) and restrict Zulip + notifications to a specified set of branches. +

+ +

+ Further configuration is possible. By default, commits traffic (pushes, commit comments), + GitHub issues traffic, and pull requests are enabled. You can exclude certain types of traffic + via the checkboxes. If you want commit traffic, issue traffic, and pull requests to go to + different places, you can use the Commit Stream and Issue Stream overrides; + otherwise, it is safe to leave these fields blank and just have it default to the Stream + setting. +

+ +

+ Click the "Update settings" button to complete the + configuration: +

+

+ +

+ Congratulations! You're done!
When team members push to + your repository, you'll get a Zulip notification that looks like this: +

+ +

diff --git a/zerver/webhooks/github_webhook/doc.html b/zerver/webhooks/github_webhook/doc.html new file mode 100644 index 0000000000..dc38f2fa65 --- /dev/null +++ b/zerver/webhooks/github_webhook/doc.html @@ -0,0 +1,36 @@ + +

+ First, create the stream you'd like to use for GitHub Webhook notifications, + and subscribe all interested parties to this stream. The integration will + use the default stream github if no stream is supplied in + the hook; you still need to create the stream even if you are using this + default. +

+ +

Next, go to your repository page and click "Settings":

+

+ +

From there, select "Webhooks":

+

+ +

Click "Add webhook".

+

+ +

Authorize yourself and configure your webhook.

+ +

In the "Payload URL" field, enter a URL constructed like this:

+ +

{{ external_api_uri_subdomain }}/v1/external/webhook_github?api_key=abcdefgh&stream=github

+ +

+ where api_key is the API key of your Zulip + bot. Select the actions that you want to result in a + Zulip notification and click Add Webhook. +

+ +

+ Congratulations! You're done!
+ Your messages will look like this: +

+ +

diff --git a/zerver/webhooks/gitlab/doc.html b/zerver/webhooks/gitlab/doc.html new file mode 100644 index 0000000000..28c0b228b5 --- /dev/null +++ b/zerver/webhooks/gitlab/doc.html @@ -0,0 +1,33 @@ +

+ First, create the stream you'd like to use for GitLab notifications, + and subscribe all interested parties to this stream. The integration will + use the default stream gitlab if no stream is supplied in + the URL; you still need to create the stream even if you are using this + default. +

+ +

+ Next, go to your repository page and click gear icon. + From there, select Webhooks: +

+

+ +

In the URL field, enter a URL constructed like this:

+ +

{{ external_api_uri_subdomain }}/v1/external/gitlab?api_key=abcdefgh&stream=gitlab

+ +

+ where api_key is the API key of your Zulip + bot. +

+

+ Select the actions that you want to result in a + Zulip notification and click Add Webhook. +

+ +

+ Congratulations! You're done!
+ Your messages will look like this: +

+ +

diff --git a/zerver/webhooks/gosquared/doc.html b/zerver/webhooks/gosquared/doc.html new file mode 100644 index 0000000000..0f11cef323 --- /dev/null +++ b/zerver/webhooks/gosquared/doc.html @@ -0,0 +1,39 @@ +

+ First, create a stream for GoSquared for where you would like to receive GoSquared notifications + and subscribe all interested parties to the stream. The integration will automatically + use the default stream gosquared if no stream is supplied, though you will + still need to create the stream manually even though it's the default. +

+ +

+ Next, go to the Zulip settings page and create a bot named GoSquared. Go to the account settings page of + your GoSquared account and under Project Settings > Services > Webhook > Add New. + Add the below URL under the section 'Enter a URL to receive requests:' and name the integration, Zulip. +

+ +

{{ external_api_uri_subdomain }}/v1/external/gosquared?api_key=abcdefgh&stream=gosquared

+ +

+ +

+ Note: api_key must be reconfigured to be the API key of your Zulip bot.
+ If you want to change the stream default that receives notifications, change stream= in the URL. +
+ To change the topic displayed by the bot, simply append &topic=name to the end of the above + URL. + Where name is your topic. +

+ +

+ Under notifications of your GoSquared account page, press Add New Notification and select when and + why you + want to be notified through Zulip. After you're done, remember to check the box of the webhook corresponding to + Zulip. +

+ +

+ Congratulations! You're all set
+ Your messages should look like this: +

+ +

diff --git a/zerver/webhooks/hellosign/doc.html b/zerver/webhooks/hellosign/doc.html new file mode 100644 index 0000000000..a6d8c05d51 --- /dev/null +++ b/zerver/webhooks/hellosign/doc.html @@ -0,0 +1,32 @@ +

+ Configuring the HelloSign integration is easy. First, create a stream + (we recommend a name like "hellosign"). +

+ +

+ Next, go to the Zulip settings page and create a Zulip bot bot + for the HelloSign integration. Note the bot API key and add + it to the URL below as api_key, and including the + name of the stream you'd like to receive the notifications + as stream= in the URL. If you'd like to hardcode + the topic used by the bot, simply append + &topic=topic_name to the end of the above URL, where + topic_name is your topic. +

+ +

{{ external_api_uri_subdomain }}/v1/external/hellosign?api_key=abcdefgh&stream=stream_name

+ +

+ Go to the account settings page of your HelloSign account and + under the Integrations tab, go to API and Account Callback. + Add the above URL with your modifications under the section 'Account Callback'. +

+ +

+ +

+ Congratulations! You're all set.
+ Your messages should look like this: +

+ +

diff --git a/zerver/webhooks/helloworld/doc.html b/zerver/webhooks/helloworld/doc.html new file mode 100644 index 0000000000..e6cec1854b --- /dev/null +++ b/zerver/webhooks/helloworld/doc.html @@ -0,0 +1,31 @@ +

Learn how Zulip integrations work with this simple Hello World example!

+ +

+ The Hello World webhook will use the test stream, which is + created by default in the Zulip dev environment. If you are running + Zulip in production, you should make sure this stream exists. +

+ +

+ Next, on your {{ settings_html|safe }}, create a Hello World bot. Construct the URL for + the Hello World bot using the API key and stream name: + {{ external_api_uri_subdomain }}/v1/external/helloworld?api_key=abcdefgh&stream=test +

+ +

To trigger a notication using this webhook, use `send_webhook_fixture_message` from the Zulip command line:

+
+ 
(zulip-venv)vagrant@vagrant-ubuntu-trusty-64:/srv/zulip$
+./manage.py send_webhook_fixture_message \
+> --fixture=zerver/fixtures/helloworld/helloworld_hello.json \
+> '--url=http://localhost:9991/api/v1/external/helloworld?api_key=<api_key>'
+
+
+ +

Or, use curl:

+
+ 
curl -X POST -H "Content-Type: application/json" -d '{ "featured_title":"Marilyn Monroe", "featured_url":"https://en.wikipedia.org/wiki/Marilyn_Monroe" }' http://localhost:9991/api/v1/external/helloworld\?api_key\=<api_key>
+
+ +

Congratulations! You're done!
Your messages may look like:

+ + diff --git a/zerver/webhooks/heroku/doc.html b/zerver/webhooks/heroku/doc.html new file mode 100644 index 0000000000..3c1ad94bb4 --- /dev/null +++ b/zerver/webhooks/heroku/doc.html @@ -0,0 +1,51 @@ +

+ Receive notifications in Zulip whenever a new version of an app is pushed to Heroku + using the Zulip Heroku plugin! +

+ +

+ First, create the stream you'd like to use for Heroku notifications, and + subscribe all interested parties to this stream. We recommend the + name heroku. +

+ +

Next, on your {{ settings_html|safe }}, create a Heroku bot.

+ +

Then, log into your account on heroku.com, and:

+ +
    +
  1. +

    + Visit the page for the project for which you'd like to generate + Zulip notifications. Click the "Resources" tab, and add the "Deploy Hooks" addon. + Choose the "HTTP Post Hook" plan, and click "Provision". +

    + + +
    2. +
  2. +

    + Click on the "Deploy Hooks" add-on that you just added. + You should be redirected to a page that looks like this: +

    + +

    + +

    + Enter the following webhook URI, replacing the bot API key + and Zulip stream with the appropriate information. +

    + +

    + {{ external_uri_scheme }}{{ external_api_path_subdomain }}/v1/external/heroku?api_key=test_api_key&stream=heroku +

    +
    3. +
+ +

+ Congratulations! You're done!
+ When you deploy to Heroku, the team can see these updates in real time in Zulip: +

+ + diff --git a/zerver/webhooks/ifttt/doc.html b/zerver/webhooks/ifttt/doc.html new file mode 100644 index 0000000000..4e04f50498 --- /dev/null +++ b/zerver/webhooks/ifttt/doc.html @@ -0,0 +1,46 @@ +

Get notifications from every event supported by IFTTT.

+

+ First, create the stream you'd like to use for IFTTT notifications, + and subscribe all interested parties to this stream. +

+ +

{{ external_api_uri_subdomain }}/v1/external/ifttt?api_key=abcdefgh&stream=ifttt

+ +

+ Next, create an IFTTT recipe, picking the service you'd like + to receive notifications from as this, + and Maker as that. +

+ +

+ Choose the Make a web request action, and + configure it as follows: +

+ + +

+ Finally, configure the request body. You need to construct a JSON + object with two parameters: content + and subject.
+ Example: + {"content": "message content", "subject": "message subject"} +
+

+

+ You will most likely want to specify some IFTTT + "Ingredients" (click the beaker to see the available + options) to customize the subject and content of your + messages; the below screenshot uses ingredients available + if this is IFTTT's incoming email service. +

+

Example configuration: + +

+ +

You're done! Example message:

+ + diff --git a/zerver/webhooks/jira/doc.html b/zerver/webhooks/jira/doc.html new file mode 100644 index 0000000000..7d8a2513b0 --- /dev/null +++ b/zerver/webhooks/jira/doc.html @@ -0,0 +1,45 @@ +

+ + If you are running JIRA version 5.2 or greater, or if you are + using the hosted JIRA provided by Atlassian, you can use the built-in + web-hook support to connect to Zulip — read on. For older, + self-hosted JIRA installs, you can use our JIRA Plugin. + +

+ +

+ First, create the stream you'd like to use for JIRA notifications, and + subscribe all interested parties to this stream. We recommend the + name jira. +

+ +

+ In your JIRA administration control panel, go to the Webhooks page. If you are using the OnDemand + hosted JIRA, follow the instructions + + on the Atlassian wiki + + for locating the Webhook UI. +

+

Give your new web hook a name, and for the URL provide the following:

+

+ {{ external_api_uri_subdomain }}/v1/external/jira?api_key=abcdefgh&stream=jira +

+ +

+ where api_key is the API key of your Zulip bot, + and stream is the stream name you want the + notifications sent to. +

+ +

+ Next, go back to Zulip and set up a stream called "jira," if it does not already exist. + (If you prefer your JIRA notifications to go to a stream other than "jira," then change the URL above to match + it.) +

+ +

+ Congratulations! You're done!
+ Updates from JIRA will be sent to the Zulip stream you specified in the JIRA web-hook. +

+ diff --git a/zerver/webhooks/librato/doc.html b/zerver/webhooks/librato/doc.html new file mode 100644 index 0000000000..6e2104e99c --- /dev/null +++ b/zerver/webhooks/librato/doc.html @@ -0,0 +1,77 @@ +

Get Zulip notifications for your Librato alerts or snapshots!

+ +

+ First, create the stream you'd like to use for Librato notifications, and + subscribe all interested parties to this stream. We recommend the + name librato. +

+ +

+ Next, on your Zulip settings + page, create a Librato bot. Please note the bot name and API key. Then: +

+ +

Alerts configuration

+ +

1. Login into your Librato account and switch to the integrations page:

+

+ +

2. From there, select "Webhook" integration:

+

+ +

3. Fill in the title and URL fields using your bot's API key

+

+ +

The default stream name is librato and default topic name is Alert alert_name.

+ +
+  URL = {{ external_api_uri }}/v1/external/librato?api_key=your_api_key
+
+ +

You can customize the stream name and topic name:

+ +
+  URL = {{ external_api_uri }}/v1/external/librato?stream=your_stream_name&topic=your_topic_name&api_key=your_api_key
+
+ + +

4. Next, go to your alerts page:

+

+ +

+ 5. Choose the alert conditions and enable the your new + webhook under "Notification Services": +

+

+ +

+ Congratulations! You're done!
+ When an alert triggers, you'll get a Zulip notification that looks like this: +

+ +

+ + +

Snapshot configuration

+ +

+ Because of limitations in Librato's API, you need to use the + Slack integration to get Librato snapshots sent into Zulip. +

+

+

Default stream name is librato and default topic name is snapshots.

+ +

+ To send a snapshot, just click at one of your chart, use + the send a snapshot option and add the proper + integration. +

+ +

+ +

+ Congratulations! You're done!
+ When a snapshot comes, you'll get a Zulip notification that looks like this: +

+ +

diff --git a/zerver/webhooks/mention/doc.html b/zerver/webhooks/mention/doc.html new file mode 100644 index 0000000000..1301018d18 --- /dev/null +++ b/zerver/webhooks/mention/doc.html @@ -0,0 +1,52 @@ +

+ First, create the stream you'd like to use for Mention Webhook notifications, + and subscribe all interested parties to this stream. The integration will + use the default stream mention if no stream is supplied in + the hook; you still need to create the stream even if you are using this + default. +

+ +

+ Next, go to your Mention feed and click on your profile in the top right corner, + click on Settings in the drop down menu: +

+

+ +

From there, select Integrations:

+

+ +

Select the Zapier integration, and click Explore Mention on Zapier!:

+

+ +

+ Search for "webhooks" in the search bar, and click on Webhooks by Zapier.
+ Scroll down and look for Add Webhooks posts for new Mentions and click on + Use this Zap: +

+

+ +

+ Select your Mention account Id and the alert that should trigger mentions + from the respective drop down menus, and click Continue +

+ +

+ Select POST on the page that says Webhooks by Zapier Action, and click + Continue. +

+ +

In the URL field, enter a URL constructed like this:

+ +

{{ external_api_uri_subdomain }}/v1/external/mention?api_key=abcdefgh&stream=mention

+ +

+ where abcdefgh should be replaced with the API key of your Zulip + bot. Select JSON for Payload Type and click Continue: +

+ +

+ Congratulations! You're done!
+ Your messages will look like this: +

+ +

diff --git a/zerver/webhooks/newrelic/doc.html b/zerver/webhooks/newrelic/doc.html new file mode 100644 index 0000000000..b5bf853dbf --- /dev/null +++ b/zerver/webhooks/newrelic/doc.html @@ -0,0 +1,32 @@ +

+ New Relic can send messages to a Zulip stream for alerts and + deploys. +

+ +

+ First, create the stream you'd like to use for New Relic + notifications, and subscribe all interested parties to this stream. We + recommend the name newrelic. +

+ +

+ Next, in your New Relic Account Settings page, click + "Integrations", then "Alerting notifications". On the "Webhook" + tab, enter the following webhook URL: +

+ +

{{ external_api_uri_subdomain }}/v1/external/newrelic?api_key=abcdefgh&stream=newrelic

+ +

+ where api_key is the API key of your Zulip bot, + and stream is the stream name you want the + notifications sent to. +

+ + + +

+ Congratulations! You're done!
Your New Relic events will + appear in Zulip: +

+ diff --git a/zerver/webhooks/pagerduty/doc.html b/zerver/webhooks/pagerduty/doc.html new file mode 100644 index 0000000000..ff029bb727 --- /dev/null +++ b/zerver/webhooks/pagerduty/doc.html @@ -0,0 +1,24 @@ +

+ First, create the stream you'd like to use for Pagerduty notifications, + and subscribe all interested parties to this stream. We recommend the + stream name pagerduty. Keep in mind you still need to create + the stream first even if you are using this recommendation. +

+ +

+ Next, in Pagerduty, select Services under Configuration on the top + of the page. +

+ + +

+ Now navigate to the service you want to integrate with Zulip. From + there, click "Add a webhook". Fill in the form like this: +

+ + + diff --git a/zerver/webhooks/papertrail/doc.html b/zerver/webhooks/papertrail/doc.html new file mode 100644 index 0000000000..350ceb626d --- /dev/null +++ b/zerver/webhooks/papertrail/doc.html @@ -0,0 +1,45 @@ +

+ Zulip supports integration with Papertrail as a + Webhook + that fires upon finding a certain log. To do this: +

+ +

+ First, create the stream you'd like to use for Papertrail + notifications, and subscribe all interested parties to this stream. We + recommend the stream name be papertrail. After create a bot named + Papertrail and note the API key. +

+ +

+ Next, log into your Papertrail Account and browse through your logs. + Search for logs you want to get alerts for and press the Save Search + to open up a modal window, then fill out the details and press the + Save & Setup an alert button. +

+ + + + + +

+ Go to the Create an alert section, press the Webhooks + link and place the below URL into the Webhook URL section. Be sure to set + the frequency to either minute, hour or day. +

+ +

{{ external_api_uri_subdomain }}/v1/external/papertrail?api_key=abcdefgh&stream=papertrail

+ + + +

+ Note: api_key is the API key of your Zulip bot, + and stream is the stream name you want the + notifications sent to. +

+ +

+ Congratulations! You're done!
Your Papertrail notifications will + appear in Zulip: +

+ diff --git a/zerver/webhooks/pingdom/doc.html b/zerver/webhooks/pingdom/doc.html new file mode 100644 index 0000000000..eb3586acd7 --- /dev/null +++ b/zerver/webhooks/pingdom/doc.html @@ -0,0 +1,35 @@ +

+ Zulip supports integration with Pingdom and can notify you of + uptime status changes from your Pingdom dashboard. +

+ +

+ First, create the stream you'd like to use for Pingdom notifications, + and subscribe all interested parties to this stream. We + recommend the name pingdom. +

+ +

{{ external_api_uri_subdomain }}/v1/external/pingdom?api_key=abcdefgh&stream=pingdom

+ +

+ where api_key is the API key of your Zulip bot, + and stream is the stream name you want the + notifications sent to. +

+ +

Next, under following url:

+

https://my.pingdom.com/reports/integration/settings

+

create your integration by clicking on Add Integration button and filling form as following:

+ + +

+ Last, during creating or editing your check, scroll down to Connect Integrations + section and ensure your integration is checked +

+ +

+ Congratulations! You're done!
Example Zulip notification + looks like this: +

+ + diff --git a/zerver/webhooks/pivotal/doc.html b/zerver/webhooks/pivotal/doc.html new file mode 100644 index 0000000000..f68044b400 --- /dev/null +++ b/zerver/webhooks/pivotal/doc.html @@ -0,0 +1,35 @@ +

+ Zulip supports integration with Pivotal Tracker and can notify you of changes +to the stories in your Pivotal Tracker project. +

+ +

+ First, create the stream you'd like to use for Pivotal Tracker +notifications, and subscribe all interested parties to this stream. We +recommend the name pivotal. +

+ +

+ Next, in the Settings page for your project, choose the Integrations +tab. Scroll down to the Activity Web Hook section, and enter +the following url: +

+ +

{{ external_api_uri_subdomain }}/v1/external/pivotal?api_key=abcdefgh&stream=pivotal

+ +

+ where api_key is the API key of your Zulip bot, +and stream is the stream name you want the +notifications sent to. +

+ +

+ Choose version 5 of the API. Zulip supports both version 3 and version 5, but +version 5 contains more information that lets Zulip format more useful messages. +

+ + + +

Congratulations! You're done!
When you make changes in Pivotal Tracker they will be reflected in Zulip: +

+ diff --git a/zerver/webhooks/semaphore/doc.html b/zerver/webhooks/semaphore/doc.html new file mode 100644 index 0000000000..44203e1cf7 --- /dev/null +++ b/zerver/webhooks/semaphore/doc.html @@ -0,0 +1,54 @@ +

Semaphore

+ +

+ See build and deploy statuses on Semaphore right in Zulip with the Zulip + Semaphore plugin! +

+ +

+ First, create the stream you'd like to use for Semaphore notifications, and + subscribe all interested parties to this stream. We recommend the + name builds. +

+ +

Next, on your {{ settings_html|safe }}, create a Semaphore bot.

+ +

Then, log into your account on semaphoreci.com, and:

+ +
    +
  1. +

    + Visit the "Project Settings" page for the project for which you'd like to generate + Zulip notifications. Click the "Notifications" tab in the left sidebar, + click on "Webhooks" in the resulting menu, and then click on "+ Add Webhook". +

    + + +
    2. +
  2. +

    You should now see a form that looks like this:

    + +

    + +

    + +

    + Enter the following webhook URI, replacing the bot email address, + bot API key, and Zulip stream with the appropriate + information. Note: the @-sign in the bot e-mail + address must be escaped to %40: +

    + +

    + {{ external_uri_scheme }}semaphore-bot%40example.com:api_key@{{ external_api_path_subdomain }}/v1/external/semaphore?stream=builds +

    +
    3. +
+ +

+ Congratulations! You're done!
When you push to Semaphore, the + team can see these updates in real time in Zulip: +

+ + diff --git a/zerver/webhooks/sentry/doc.html b/zerver/webhooks/sentry/doc.html new file mode 100644 index 0000000000..de0119dac5 --- /dev/null +++ b/zerver/webhooks/sentry/doc.html @@ -0,0 +1,38 @@ +

+ Zulip supports integration with Sentry and can notify you of + issues that occurred in your project. +

+ +

+ First, create the stream you'd like to use for Sentry notifications, + and subscribe all interested parties to this stream. We + recommend the name sentry. Then, construct + the Sentry webhook URL as follows: +

+ +

{{ external_api_uri_subdomain }}/v1/external/sentry?api_key=abcdefgh&stream=sentry

+ +

+ where api_key is the API key of your Zulip bot, + and stream is the stream name you want the + notifications sent to. +

+ +

Next, from Sentry dashboard choose your project.

+

+

From the menu on the right, choose Settings

+
+

On the settings page, from the menu on the left, choose Notifications
+ In the Inactive Integrations section, choose WEBHOOKS

+
+

In the WebHooks box, insert the above webhook + URL into the Callback URLs* field.

+
+

And click Save Changes

+ +

+ Congratulations! You're done!
You will receive Zulip notifications + like this whenever a new Sentry alert is triggered: +

+ + diff --git a/zerver/webhooks/solano/doc.html b/zerver/webhooks/solano/doc.html new file mode 100644 index 0000000000..a8cce4e1d5 --- /dev/null +++ b/zerver/webhooks/solano/doc.html @@ -0,0 +1,32 @@ +

+ First, create the stream you'd like to use for Solano Labs CI Build notifications, and + subscribe all interested parties to this stream. The integration will use the default + stream solano labs if no stream is supplied in the hook; you still need + to create the stream even if you are using this default. +

+ +

+ Next, setup a bot that you would like to use with this integration. You will need its + API key. +

+ +

+ Next, follow + these instructions for Outgoing Web Hooks to configure a webhook for your Solano + Labs Organization and choose the repositories that should trigger a webhook a notification. +

+ +

Enter a url of the following format into the URL field:

+ +

{{ external_api_uri_subdomain }}/v1/external/solano?api_key=abcdefgh&stream=solano_labs

+ +

Where abcdefgh should be replaced with the API key of the bot you + created earlier.

+ +

Leave the Username and Password fields blank and click Add Web Hook

+

Congratulations! You're Done!

+ +

Your messages will look like this:

+ + + diff --git a/zerver/webhooks/stash/doc.html b/zerver/webhooks/stash/doc.html new file mode 100644 index 0000000000..ce8e77034c --- /dev/null +++ b/zerver/webhooks/stash/doc.html @@ -0,0 +1,68 @@ +

Stash

+ +

+ See what the team is committing to Stash right in Zulip with the Zulip + Stash plugin! +

+ +

+ First, create the stream you'd like to use for Stash notifications, and + subscribe all interested parties to this stream. We recommend the + name commits. +

+ +

Next, on your {{ settings_html|safe }}, create a Stash bot.

+ +

Then:

+ +
    +
  1. +

    + Visit the Settings page for the Project that you'd like to generate + Zulip notifications. Click the "Hooks" option in the left sidebar, and + click "Add Hook" on the resulting page. Click the "Search for hook + plugins" link: +

    + + +
    2. +
  2. +

    + On the search results page, look for and install the "Post-Receive + WebHook for Stash" plugin: +

    + + +
    3. +
  3. +

    + Return to the Settings page for this Project and click the "Hooks" + option in the left sidebar. The newly-installed post-receive webhook + plugin is now listed in the "Post-receive" hooks section. Click the + edit icon next to the hook to configure it: +

    + + +
    4. +
  4. +

    + Supply the following webhook URL, replacing the bot email address, + bot API key, and Zulip stream with the appropriate + information. Note: the @-sign in the bot e-mail + address must be escaped to %40: +

    + +

    + {{ external_uri_scheme }}stash-bot%40example.com:api_key@{{ external_api_path_subdomain }}/v1/external/stash?stream=commits +

    + + +
    5. +
+ +

+ Congratulations! You're done!
When you push to Stash, the + team can see these updates in real time in Zulip: +

+ + diff --git a/zerver/webhooks/stripe/doc.html b/zerver/webhooks/stripe/doc.html new file mode 100644 index 0000000000..4cee81e6e9 --- /dev/null +++ b/zerver/webhooks/stripe/doc.html @@ -0,0 +1,68 @@ +

+ You can choose to be notified whenever certain events are triggered on Stripe + by adding a webhook to your Stripe account. First, create a stream where the events + are to be sent. +

+ +

Next, on your {{ settings_html|safe }}, create a Stripe bot.

+ +

+ Add a webhook to your Stripe account by going to "Your account"->"Account + settings"->"Webhooks"->"Add Endpoint" and adding the following URL, + replacing the bot email address (with the @sign escaped to %40), + bot API key, Zulip stream, and Zulip topic with the appropriate values: +

+ +

e.g.

+ + +{{ external_uri_scheme }}stripe-bot%40example.com:api_key@{{ external_api_path_subdomain }}/v1/external/stripe?stream=sales%26topic=Stripe + +

+ {% if 'http:' in external_uri_scheme %} + Note that Stripe will only accept https webhooks! + {% endif %} +

+ + + +

+ To set up different topics for different events, create separate webhooks + for those events, customizing the URL stream and topic for each. +

+ + + +

+ Congratulations! +

+ +

+ You will now receive notifications for the events you have chosen. + Zulip currently supports the following events: +

+ + + + diff --git a/zerver/webhooks/taiga/doc.html b/zerver/webhooks/taiga/doc.html new file mode 100644 index 0000000000..dc83ca02c8 --- /dev/null +++ b/zerver/webhooks/taiga/doc.html @@ -0,0 +1,94 @@ +

+ Go on your {{ settings_html|safe }}, create a Taiga bot. + Please note the bot name and API key. +

+ +

+ Since Taiga allows you to integrate services on a per + project basis, you have to perform the following steps + for every project that you want to send + notifications to Zulip. +

+ +
    +
  1. +

    Go to Admin > Integration > Webhooks menu.

    +
    2. +
  2. +

    Click Add a new webhook.

    +
    3. +
  3. +

    Fill out the form by following the instructions:

    +
      +
    • + Name - to recognize this service, preferably Zulip +
      • +
    • + URL - + 
      {{ external_api_uri_subdomain }}/v1/external/taiga?stream=STREAM_NAME&topic=TOPIC_NAME&api_key=BOT_API_KEY
      +
        +
      • + STREAM_NAME - The url-encoded name of + stream which you want to receive notifications. + You can use an existing Zulip stream or create a + new one for this. +
        • +
      • + TOPIC_NAME - The url-encoded + topic where your Taiga notifications will be + posted. (Read the notes below.) +
        • +
      • BOT_API_KEY - API key created in Zulip.
        • +
      +
      • +
    +

    + Remember to url-encode the stream and topic + names. E.g. spaces need to be replaced + with %20 (e.g. so if you want your stream + to be called "My awesome project", STREAM_NAME + should be My%20awesome%20project). +

    +
    4. +
  4. + Secret key - once again the API key created in Zulip. +
    5. + +
  5. +

    Click Save once you've finished filling out the form.

    +
    6. +
+

+ That's it! Your actions on Taiga should now cause + notifications on the Zulip stream you specified above. + +

+
+ +

+ There are two different ways you may want to consider + when organizing your Taiga - Zulip integration: +

+ diff --git a/zerver/webhooks/teamcity/doc.html b/zerver/webhooks/teamcity/doc.html new file mode 100644 index 0000000000..6beb297eec --- /dev/null +++ b/zerver/webhooks/teamcity/doc.html @@ -0,0 +1,58 @@ +

See your Teamcity build status in Zulip!

+ +

+ First, create the stream you'd like to use for Teamcity + notifications, and subscribe all interested parties to this stream. We + recommend the name teamcity. +

+ +

+ Next, set up a bot for the integration. You'll need the bot's API key + to construct a URL for Teamcity. +

+ +

+ Next, install the tcWebHooks plugin + onto your Teamcity server. Follow the plugin instructions in your + Teamcity documentation, or refer to + the online Teamcity + documentation. +

+ +

+ Next, in your Teamcity project overview page, + click the "Webhooks" tab, and add a new project webhook. + Enter the following URL: +

+ +

{{ external_api_uri_subdomain }}/v1/external/teamcity?api_key=abcdefgh&stream=teamcity

+ +

+ where api_key is the API key of your Zulip bot, + and stream is the stream name you want the + notifications sent to. +

+ +

+ Uncheck all "Trigger on Events" options, and check + "Trigger when build is Successful" and "Trigger when build Fails". + Optionally, check "Only trigger when build changes from Failure to Success" + and "Only trigger when build changes from Success to Failure". +

+ +

Set the Payload Format to "JSON" and save your webhook.

+ + + +

+ Congratulations! You're done!
Your Teamcity build + notifications will appear in Zulip: +

+ + +

+ Personal Builds
When a user runs a personal build, if Zulip can + map their Teamcity username to a Zulip user, that Zulip user will receive a + private message with the result of their personal build. +

+ diff --git a/zerver/webhooks/transifex/doc.html b/zerver/webhooks/transifex/doc.html new file mode 100644 index 0000000000..5383f62213 --- /dev/null +++ b/zerver/webhooks/transifex/doc.html @@ -0,0 +1,32 @@ +

+ First, create the stream you'd like to use for Transifex + notifications, and subscribe all interested parties to this stream. We + recommend the name transifex. +

+ +

+ Next, set up a bot for the integration. You'll need the bot's API key + to construct a URL for Transifex. +

+ +

{{ external_api_uri_subdomain }}/v1/external/transifex?api_key=abcdefgh&stream=transifex

+ +

+ where api_key is the API key of your Zulip bot, + and stream is the stream name you want the + notifications sent to. +

+ +

+ Next, in Transifex, go to your project settings page: + Project Details → Manage → Edit Project and scroll down to + WEB HOOK URL. Paste the URL you constructed into the box and + save your changes. +

+ +

+ Congratulations! You're done!
+ Example message: +

+ + diff --git a/zerver/webhooks/travis/doc.html b/zerver/webhooks/travis/doc.html new file mode 100644 index 0000000000..a3300ccbe4 --- /dev/null +++ b/zerver/webhooks/travis/doc.html @@ -0,0 +1,28 @@ +

See your Travis CI build notifications in Zulip!

+ +

+ First, create the stream you'd like to use for notifications, and subscribe + all interested parties to this stream. We recommend the name travis. +

+ +

+ Next, set up a bot for the integration. You'll need the bot's API key + to construct a URL for Travis CI. +

+ +

+ Finally, set up a webhook in your .travis.yml file: +

+ +
+notifications:
+webhooks:
+- {{ external_api_uri_subdomain }}/v1/external/travis?stream=travis&topic=build-status&api_key=abcdefgh
+
+ +

+ Congratulations! You're done!
When a code build occurs, + you're receive a notification on the specified stream and topic. +

+ + diff --git a/zerver/webhooks/trello/doc.html b/zerver/webhooks/trello/doc.html new file mode 100644 index 0000000000..8232cdf0be --- /dev/null +++ b/zerver/webhooks/trello/doc.html @@ -0,0 +1,87 @@ +

+ This webhook integration for Trello is the recommended way to + integrate with Trello, and should support all the features of + the legacy Trello cron-based + integration. +

+ +

+ First, create the stream you'd like to use for Trello notifications, + and subscribe all interested parties to this stream. We recommend the + name trello. +

+ +

+ Your webhook URL is:
+ {{ external_api_uri_subdomain }}/v1/external/trello?api_key=abcdefgh&stream=trello
+ where api_key is the API key of your Zulip bot, + and stream is the stream name you want the notifications sent to. +

+ +

+ Before you create a webhook, + you'll need to follow the steps below to get an APPLICATION_KEY, and a UserToken, + and to fetch the board's idModel. +

+ +

+ To generate the APPLICATION_KEY, open this URL in your web browser:
+ https://trello.com/1/appkey/generate. +

+ +

+ To generate a read access token, fill in and open this URL in the browser while logged into your Trello account: + https://trello.com/1/authorize?key=<APPLICATION_KEY>&name=Issue+Manager&expiration=never&response_type=token&scope=read
+ You will receive your UserToken. Note it. +

+ +

+ Within the the board URL, you can find the TRELLO_BOARD_SHORT_ID. + The Trello URL format is:
+ https://trello.com/b/TRELLO_BOARD_SHORT_ID/boardName. +

+ +

+ Now you have the APPLICATION_KEY, UserToken and TRELLO_BOARD_SHORT_ID.
+ Construct this URL and open it in your web browser:
+ https://api.trello.com/1/board/<TRELLO_BOARD_SHORT_ID>?key=<APPLICATION_KEY>&token=<UserToken>
+ You'll receive some JSON. Within that, find the id value. That's your idModel; note it. +

+ +

+ Now you have the ingredients to create your webhook. + Send a POST request to this URL with this data: + https://api.trello.com/1/tokens/<UserToken>/webhooks/?key=<APPLICATION_KEY> +

+
{
+    "description": "Webhook for Zulip integration",
+    "callbackURL": "<URL_TO_ZULIP_WEBHOOK_FROM_SECOND_STEP>",
+    "idModel": "<ID_MODEL>",
+}
+
+ You can use curl to do this:
+
curl 'https://api.trello.com/1/tokens/<UserToken>/webhooks/?key=<APPLICATION_KEY>'
+-H 'Content-Type: application/json' -H 'Accept: application/json'
+--data-binary $'{\n  "description": "Webhook for Zulip integration",\n  "callbackURL": "<URL_TO_ZULIP_WEBHOOK_FROM_SECOND_STEP>",\n  "idModel": "<ID_MODEL>"\n}'
+--compressed
+
+

+ The response from Trello should look like:
+

+
{
+    "id": "<WEBHOOK_ID>",
+    "description": "Webhook for Zulip integration",
+    "idModel": "<ID_MODEL>",
+    "callbackURL": "<URL_TO_ZULIP_WEBHOOK_FROM_SECOND_STEP>",
+    "active": true
+}
+
+

+ Congratulations! You've created a webhook and your integration is live. +

+ +

+ When you make changes in on this board in Trello, you will + receive Zulip notifications like this: +

+

diff --git a/zerver/webhooks/updown/doc.html b/zerver/webhooks/updown/doc.html new file mode 100644 index 0000000000..46c26ec213 --- /dev/null +++ b/zerver/webhooks/updown/doc.html @@ -0,0 +1,26 @@ +

+ See Updown reports in Zulip! This is great to be up to date with + downtime in the services you monitor with Updown! +

+ +

+ First, create the stream you'd like to use for updown + notifications, and subscribe all interested parties to this + stream. We recommend the name updown. +

+ +

+ Go to your Updown + settings page and in WEBHOOKS section, enter + the following as the URL: +

+ +

{{ external_api_uri_subdomain }}/v1/external/updown?api_key=abcdefgh&stream=updown

+ + +

+ Congratulations! You're done!
+ Now you'll receive Updown notifications for your service in Zulip. +

+ + diff --git a/zerver/webhooks/yo/doc.html b/zerver/webhooks/yo/doc.html new file mode 100644 index 0000000000..319b9513f9 --- /dev/null +++ b/zerver/webhooks/yo/doc.html @@ -0,0 +1,33 @@ +

See your Yo App notifications in Zulip!

+ +

+ Go to your Zulip settings and set up a Zulip bot for the + integration. You'll need the bot's API key to construct a URL for + Yo App Callback. +

+ +

You will receive your notifications as a private message between you and the bot.

+ +

Create a URL using your bot's API key and the email address associated with your Zulip account:

+ +
{{ external_api_uri_subdomain }}/api/v1/external/yo?email=awesome@zulip.example.com&api_key=abcdefgh
+ +

Copy the URL created and go to yoapi.justyo.co.

+

Sign in using your username and password and go to Edit Profile.

+ + + +

Paste the URL in the Callback field and click on Update.

+ +

+ Congratulations! You're done!
When someone sends your username a Yo, + you'll receive a notification as a private message from the bot + like this: +

+ + + +

+ Multiple users can use the same Yo bot; each user should use + their own Zulip account email in the webhook URL. +

diff --git a/zerver/webhooks/zapier/doc.html b/zerver/webhooks/zapier/doc.html new file mode 100644 index 0000000000..287353aee5 --- /dev/null +++ b/zerver/webhooks/zapier/doc.html @@ -0,0 +1,42 @@ +

Get notifications from every event supported by Zapier.

+

First, create the stream you'd like to use for Zapier notifications, + and subscribe all interested parties to this stream.

+ +

{{ external_api_uri_subdomain }}/v1/external/zapier?api_key=abcdefgh&stream=zapier

+ +

+ Next, create a ZAP, picking the service you'd like + to receive notifications from as Trigger (Step 1) +

+ + +

and Webhook as Action (Step 2).

+ + +

As Step 2 action please choose POST

+ + +

+ Configure Set up Webhooks by Zapier POST as follows: + +

+

+ +

+ Finally, configure Data. + You have to add 2 fields: +

+

+ +

Example configuration:

+ + +

You're done! Example message:

+ + diff --git a/zerver/webhooks/zendesk/doc.html b/zerver/webhooks/zendesk/doc.html new file mode 100644 index 0000000000..0d41e09041 --- /dev/null +++ b/zerver/webhooks/zendesk/doc.html @@ -0,0 +1,81 @@ +

+ First, create the stream you'd like to use for Zendesk notifications, + and subscribe all interested parties to this stream. We recommend the + stream name zendesk. Keep in mind you still need to create + the stream first even if you are using this recommendation. +

+ +

+ Next, in Zendesk, open your Admin view via gear in the bottom-left + corner. In the Admin view, click on Extensions, then click "add + target". +

+ + + +

From there, click "URL target". Fill in the form like this:

+ + + + +

+ Now select "Test Target" and click Submit. A test message should + appear in the zendesk stream. If the message was received, save the + target by selecting "Create target" and clicking Submit. +

+ +

+ From here, add a new trigger. You'll do this for every action you want + to create a Zulip notification. Triggers are added by selecting Triggers + in the left menu and then clicking "add trigger" in the top right. +

+ + + +

+ Let's say you want a notification each time a ticket is updated. Put + in a descriptive title like "Announce ticket update". Under "Meet all of + the folllowing conditions" select "Ticket: is..." and then select + Updated. In the "Perform these actions" section select "Notification: + Notify target" then select Zulip. +

+ +

+ Next we need need to enter the message body into Message. You can use + Zulip markdown and the Zendesk placeholders when creating your message. + You can copy this example template: +

+{% raw %} +
Ticket [#{{ ticket.id }}: {{ ticket.title }}]({{ ticket.link }}), was updated by {{ current_user.name }}
+
+* Status: {{ ticket.status }}
+* Priority: {{ ticket.priority }}
+* Type: {{ ticket.ticket_type }}
+* Assignee: {{ ticket.assignee.name }}
+* Tags: {{ ticket.tags }}
+* Description:
+``` quote
+{{ ticket.description }}
+```
+{% endraw %} + + + +

Finally, click Submit.

+ +

+ Congratulations! You're Done!
When a ticket is updated + you will see a notification like the following, to the stream + zendesk, with a topic that matches the ticket's subject + name: +

+ diff --git a/zproject/settings.py b/zproject/settings.py index b654714448..3dfb62057d 100644 --- a/zproject/settings.py +++ b/zproject/settings.py @@ -279,6 +279,7 @@ TEMPLATES = [ 'BACKEND': 'zproject.jinja2.backends.Jinja2', 'DIRS': [ os.path.join(DEPLOY_ROOT, 'templates'), + os.path.join(DEPLOY_ROOT, 'zerver', 'webhooks'), ], 'APP_DIRS': True, 'OPTIONS': {