Skip to content

Docs: Split email notifications and webhook notifications into separate howtos #10396

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Jun 9, 2023
Merged

Docs: Split email notifications and webhook notifications into separate howtos #10396

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
20c7e66
Split email notifications and webhook notifications into separate howtos
benjaoming Jun 6, 2023
5ddd445
Updates re: review @ericholscher
benjaoming Jun 7, 2023
fea3fc6
More review feedback addressed
benjaoming Jun 7, 2023
e60ca66
Update several parts of copy to adapt to the split
benjaoming Jun 7, 2023
33b3b9c
Dot the i's
benjaoming Jun 7, 2023
8df4c44
Adds a note about PR notifications being skipped
benjaoming Jun 8, 2023
1454899
prefer "documentation builds"
benjaoming Jun 8, 2023
3368ed9
Trim out a seealso to give the other two more prominence
benjaoming Jun 8, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 13 additions & 7 deletions docs/user/build-notifications.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,13 @@
Build Notifications and Webhooks
================================
Build notifications via webhooks and email
==========================================
Copy link
Contributor Author

@benjaoming benjaoming Jun 7, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ericholscher

re: naming is hard

I changed the feature page to have this title instead. I think it's clearer than the previous one.

I think we should try to use:

  • "Email notifications" when it's the feature in particular and when we want to have a short and sweet name
  • "Build notifications [via webhooks/email]" when we are talking about the value of having instant build feedback more broadly. It's also really good to say "build notifications via webhook" rather than just "webhooks" since the latter can already mean 3 different types of webhooks... incoming (our API), outgoing (GitHub's API) and build notifications (calling other webhooks with payload templates).

Oh yes, and of course we also say "build status webhooks" 🙃 Not on the website, it just says "webhooks" :)

We could remove "build status webhooks" and say "build notifications via webhooks" or "notification webhooks". It's not any big thing, though, anything containing the word "webhook" is bound to be a bit technical :)


Read the Docs features a number of build notification mechanisms.
Build notifications can alert you when your builds fail so you can take immediate action.
We offer the following methods for being notified:

Email notifications:
Read the Docs allows you to configure emails that can be sent on failing builds.
This makes sure you know when your builds have failed.
Read the Docs allows you to configure build notifications via email.
When builds fail,
configured email addresses are notified.

Build Status Webhooks:
Build notifications can happen via :term:`webhooks <webhook>`.
Expand All @@ -17,8 +18,13 @@ Build Status Webhooks:
Webhooks can be customized through your own template and a variety of variable substitutions.

.. seealso::
:doc:`/guides/build-notifications`
All the practical steps for setting up build notifications
:doc:`/guides/build/email-notifications`
Enable email notifications on failed builds,
so you always know that your docs are deploying successfully.

:doc:`/guides/build/webhooks`
Steps for setting up build notifications via webhooks,
including examples for popular platforms like Slack and Discord.

:doc:`pull-requests`
Similarly to build notifications, you can also configure automated feedback for your pull requests.
33 changes: 33 additions & 0 deletions docs/user/guides/build/email-notifications.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
How to setup email notifications
================================

In this brief guide,
you can learn how to setup a simple build notification via email.

Read the Docs allows you to configure emails that will be notified on failing builds.
This makes sure that you are aware of failures happening in an otherwise automated process.

.. seealso::

:doc:`/guides/build/webhooks`
How to use webhooks to be notified about builds on popular platforms like Slack and Discord.

:doc:`/pull-requests`
Configure automated feedback and documentation site previews for your pull requests.


Email notifications
-------------------

Follow these steps to add an email address to be notified about build failures:

* Go to :menuselection:`Admin --> Notifications` in your project.
* Fill in the **Email** field under the **New Email Notifications** heading
* Press :guilabel:`Add` and the email is saved and will be displayed in the list of **Existing notifications**.

The newly added email address will be notified once a build fails.


.. note::

We don't send email notifications on :doc:`builds from pull requests </pull-requests>`.
16 changes: 10 additions & 6 deletions docs/user/guides/build/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,14 @@
How-to guides: build process
============================

⏩️ :doc:`Setup build notifications and webhooks </guides/build-notifications>`
Build notifications can alert you when your builds fail so you can take immediate action.
In this guide,
you will learn how to get notified through various available channel integrations,
including email and chat.
⏩️ :doc:`Setup email notifications </guides/build/email-notifications>`
Email notifications can alert you when your builds fail.
This is the most simple way to monitor your documentation builds,
it only requires you to switch it on.

⏩️ :doc:`Setup webhook notifications </guides/build/webhooks>`
Webhook notifications can alert you when your builds fail so you can take immediate action.
We show examples of how to use the webhooks on popular platforms like Slack and Discord.

⏩️ :doc:`Configuring pull request builds </guides/pull-requests>`
Have your documentation built and access a preview for every :doc:`pull request builds </pull-requests>`.
Expand All @@ -28,7 +31,8 @@ How-to guides: build process
:maxdepth: 1
:hidden:

Setup build notifications and webhooks </guides/build-notifications>
Setup email notifications </guides/build/email-notifications>
Setup webhook notifications </guides/build/webhooks>
Configuring pull request builds </guides/pull-requests>
Using custom environment variables </guides/environment-variables>
Managing versions automatically </guides/automation-rules>
197 changes: 92 additions & 105 deletions docs/user/guides/build-notifications.rst → docs/user/guides/build/webhooks.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,46 +1,28 @@
How to setup build notifications and webhooks
=============================================
How to setup build status webhooks
==================================
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess we should be systematic about calling the feature "build status webhooks" since that's how it is right now.

If we're gonna do anything more drastic, I think it should include the Dashboard terminology, so I would just save that for later..


In this guide, you can learn how to setup a number of build notification mechanisms.
Build notifications can alert you when your builds fail so you can take immediate action.
In this guide,
you can learn how to setup build notifications via webhooks.

.. note::
Read the Docs can notify external :term:`webhooks <webhook>` when builds are triggered, successful or failed.
In that way,
you can receive build notifications in your own monitoring channels and be alerted you when your builds fail so you can take immediate action.
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is new


Currently we don't send notifications or trigger :term:`webhooks <webhook>`
on :doc:`builds from pull requests </pull-requests>`.
.. seealso::

:doc:`/guides/build/email-notifications`
Setup basic email notifications for build failures.

.. tip::
:doc:`/pull-requests`
Similarly to build notifications, you can also configure automated feedback for your pull requests.


.. contents:: Contents
:local:


Email notifications
-------------------

Read the Docs allows you to configure emails that can be sent on failing builds.
This makes sure you know when your builds have failed.

Take these steps to enable build notifications using email:
Configure automated feedback and documentation site previews for your pull requests.

* Go to :guilabel:`Admin` > :guilabel:`Notifications` in your project.
* Fill in the **Email** field under the **New Email Notifications** heading
* Submit the form

You should now get notified by email when your builds fail!

Build status webhooks
---------------------

Read the Docs can also send webhooks when builds are triggered, successful or failed.

Take these steps to enable build notifications using a webhook:

* Go to :guilabel:`Admin` > :guilabel:`Webhooks` in your project.
* Go to :menuselection:`Admin --> Webhooks` in your project.
* Fill in the **URL** field and select what events will trigger the webhook
* Modify the payload or leave the default (see below)
* Click on :guilabel:`Save`
Expand Down Expand Up @@ -79,6 +61,11 @@ you will see the server response, the webhook request, and the payload.

Activity of a webhook

.. note::

We don't trigger :term:`webhooks <webhook>` on :doc:`builds from pull requests </pull-requests>`.


Custom payload examples
~~~~~~~~~~~~~~~~~~~~~~~

Expand All @@ -93,81 +80,81 @@ and in the following section you will find all the available variables.

Custom payload

Slack
+++++

.. code-block:: json

{
"attachments": [
{
"color": "#db3238",
"blocks": [
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "*Read the Docs build failed*"
.. tabs::

.. tab:: Slack

.. code-block:: json

{
"attachments": [
{
"color": "#db3238",
"blocks": [
{
"type": "section",
"text": {
"type": "mrkdwn",
"text": "*Read the Docs build failed*"
}
},
{
"type": "section",
"fields": [
{
"type": "mrkdwn",
"text": "*Project*: <{{ project.url }}|{{ project.name }}>"
},
{
"type": "mrkdwn",
"text": "*Version*: {{ version.name }} ({{ build.commit }})"
},
{
"type": "mrkdwn",
"text": "*Build*: <{{ build.url }}|{{ build.id }}>"
}
]
}
]
}
},
{
"type": "section",
"fields": [
{
"type": "mrkdwn",
"text": "*Project*: <{{ project.url }}|{{ project.name }}>"
},
{
"type": "mrkdwn",
"text": "*Version*: {{ version.name }} ({{ build.commit }})"
},
{
"type": "mrkdwn",
"text": "*Build*: <{{ build.url }}|{{ build.id }}>"
}
]
}
]
}
]
}

More information on `the Slack Incoming Webhooks documentation <https://api.slack.com/messaging/webhooks>`_.

Discord
+++++++

.. code-block:: json

{
"username": "Read the Docs",
"content": "Read the Docs build failed",
"embeds": [
{
"title": "Build logs",
"url": "{{ build.url }}",
"color": 15258703,
"fields": [
{
"name": "*Project*",
"value": "{{ project.url }}",
"inline": true
},
{
"name": "*Version*",
"value": "{{ version.name }} ({{ build.commit }})",
"inline": true
},
{
"name": "*Build*",
"value": "{{ build.url }}"
}
]
}
]
}
]
}

More information on `the Slack Incoming Webhooks documentation <https://api.slack.com/messaging/webhooks>`_.

.. tab:: Discord

.. code-block:: json

{
"username": "Read the Docs",
"content": "Read the Docs build failed",
"embeds": [
{
"title": "Build logs",
"url": "{{ build.url }}",
"color": 15258703,
"fields": [
{
"name": "*Project*",
"value": "{{ project.url }}",
"inline": true
},
{
"name": "*Version*",
"value": "{{ version.name }} ({{ build.commit }})",
"inline": true
},
{
"name": "*Build*",
"value": "{{ build.url }}"
}
]
}
]
}

More information on `the Discord webhooks documentation <https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks>`_.
More information on `the Discord webhooks documentation <https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks>`_.

Variable substitutions reference
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -213,7 +200,7 @@ Variable substitutions reference
Version name.

Validating the payload
~~~~~~~~~~~~~~~~~~~~~~
----------------------

After you add a new webhook, Read the Docs will generate a secret key for it
and uses it to generate a hash signature (HMAC-SHA256) for each payload
Expand Down Expand Up @@ -255,7 +242,7 @@ like this:
)

Legacy webhooks
~~~~~~~~~~~~~~~
---------------

Webhooks created before the custom payloads functionality was added to Read the Docs
send a payload with the following structure:
Expand Down
7 changes: 5 additions & 2 deletions docs/user/guides/setup/git-repo-manual.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -139,8 +139,11 @@ Use this URL when setting up a new integration with your provider ^^ these steps

.. seealso::

:doc:`/guides/build-notifications`
Learn how to add custom build notifications.
:doc:`/guides/build/email-notifications`
Quickly enable email notifications.

:doc:`/guides/build/webhooks`
Learn how to add custom webhook notifications.


.. _webhook-integration-generic:
Expand Down