Skip to content

Docs: Split up Build Notifications into feature/reference and how-to (Diátaxis) #9686

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 1 commit into from
Nov 1, 2022
Merged

Docs: Split up Build Notifications into feature/reference and how-to (Diátaxis) #9686

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
284 changes: 15 additions & 269 deletions docs/user/build-notifications.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,278 +1,24 @@
Build Notifications and Webhooks
================================

.. note::
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.

Currently we don't send notifications or trigger webhooks
on :doc:`builds from pull requests </pull-requests>`.
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.

Email notifications
-------------------
Build Status Webhooks:
Build notifications can happen via webhooks.
This means that we are able to support a wide variety of services that receive 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.
Slack and Discord are supported through ready-made templates.

Take these steps to enable build notifications using email:
Webhooks can be customized through your own template and a variety of variable substitutions.

* Go to :guilabel:`Admin` > :guilabel:`Notifications` in your project.
* Fill in the **Email** field under the **New Email Notifications** heading
* Submit the form
.. seealso::
:doc:`/guides/build-notifications`
All the practical steps for setting up build notifications
Copy link
Contributor Author

Choose a reason for hiding this comment

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

The above added lines are all new texts.


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.
* 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`

.. figure:: /_static/images/webhooks-events.png
:align: center
:alt: URL and events for a webhook

URL and events for a webhook

Every time one of the checked events triggers,
Read the Docs will send a POST request to your webhook URL.
The default payload will look like this:

.. code-block:: json

{
"event": "build:triggered",
"name": "docs",
"slug": "docs",
"version": "latest",
"commit": "2552bb609ca46865dc36401dee0b1865a0aee52d",
"build": "15173336",
"start_date": "2021-11-03T16:23:14",
"build_url": "https://readthedocs.org/projects/docs/builds/15173336/",
"docs_url": "https://docs.readthedocs.io/en/latest/"
}

When a webhook is sent, a new entry will be added to the
"Recent Activity" table. By clicking on each individual entry,
you will see the server response, the webhook request, and the payload.

.. figure:: /_static/images/webhooks-activity.png
:align: center
:alt: Activity of a webhook

Activity of a webhook

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

You can customize the payload of the webhook to suit your needs,
as long as it is valid JSON. Below you have a couple of examples,
and in the following section you will find all the available variables.

.. figure:: /_static/images/webhooks-payload.png
:width: 80%
:align: center
:alt: Custom payload

Custom payload

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 }}>"
}
]
}
]
}
]
}

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 Discord webhooks documentation <https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks>`_.

Variable substitutions reference
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``{{ event }}``
Event that triggered the webhook, one of ``build:triggered``, ``build:failed``, or ``build:passed``.

``{{ build.id }}``
Build ID.

``{{ build.commit }}``
Commit corresponding to the build, if present (otherwise ``""``).

``{{ build.url }}``
URL of the build, for example ``https://readthedocs.org/projects/docs/builds/15173336/``.

``{{ build.docs_url }}``
URL of the documentation corresponding to the build,
for example ``https://docs.readthedocs.io/en/latest/``.

``{{ build.start_date }}``
Start date of the build (UTC, ISO format), for example ``2021-11-03T16:23:14``.

``{{ organization.name }}``
Organization name (Commercial only).

``{{ organization.slug }}``
Organization slug (Commercial only).

``{{ project.slug }}``
Project slug.

``{{ project.name }}``
Project name.

``{{ project.url }}``
URL of the project :term:`dashboard`.

``{{ version.slug }}``
Version slug.

``{{ version.name }}``
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
that is included in the ``X-Hub-Signature`` header of the request.

.. figure:: /_static/images/webhooks-secret.png
:width: 80%
:align: center
:alt: Webhook secret

Webhook secret

We highly recommend using this signature
to verify that the webhook is coming from Read the Docs.
To do so, you can add some custom code on your server,
like this:

.. code-block:: python

import hashlib
import hmac
import os


def verify_signature(payload, request_headers):
"""
Verify that the signature of payload is the same as the one coming from request_headers.
"""
digest = hmac.new(
key=os.environ["WEBHOOK_SECRET"].encode(),
msg=payload.encode(),
digestmod=hashlib.sha256,
)
expected_signature = digest.hexdigest()

return hmac.compare_digest(
request_headers["X-Hub-Signature"].encode(),
expected_signature.encode(),
)

Legacy webhooks
~~~~~~~~~~~~~~~

Webhooks created before the custom payloads functionality was added to Read the Docs
send a payload with the following structure:

.. code-block:: json

{
"name": "Read the Docs",
"slug": "rtd",
"build": {
"id": 6321373,
"commit": "e8dd17a3f1627dd206d721e4be08ae6766fda40",
"state": "finished",
"success": false,
"date": "2017-02-15 20:35:54"
}
}

To migrate to the new webhooks and keep a similar structure,
you can use this payload:

.. code-block:: json

{
"name": "{{ project.name }}",
"slug": "{{ project.slug }}",
"build": {
"id": "{{ build.id }}",
"commit": "{{ build.commit }}",
"state": "{{ event }}",
"date": "{{ build.start_date }}"
}
}
:doc:`pull-requests`
Similarly to build notifications, you can also configure automated feedback for your pull requests.
1 change: 1 addition & 0 deletions docs/user/guides/administrators.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,3 +19,4 @@ have a look at our :doc:`/tutorial/index`.
deprecating-content
pdf-non-ascii-languages
importing-private-repositories
Setup Build Notifications <build-notifications>
Loading