1- How to setup build notifications and webhooks
2- =============================================
1+ How to setup build status webhooks
2+ ==================================
33
4- In this guide, you can learn how to setup a number of build notification mechanisms.
5- Build notifications can alert you when your builds fail so you can take immediate action .
4+ In this guide,
5+ you can learn how to setup build notifications via webhooks .
66
7- .. note ::
7+ When a documentation build is *triggered *, *successful * or *failed *,
8+ Read the Docs can notify external APIs using :term: `webhooks <webhook> `.
9+ In that way,
10+ you can receive build notifications in your own monitoring channels and be alerted you when your builds fail so you can take immediate action.
811
9- Currently we don't send notifications or trigger :term: `webhooks <webhook> `
10- on :doc: `builds from pull requests </pull-requests >`.
12+ .. seealso ::
1113
14+ :doc: `/guides/build/email-notifications `
15+ Setup basic email notifications for build failures.
1216
13- .. tip ::
1417 :doc: `/pull-requests `
15- Similarly to build notifications, you can also configure automated feedback for your pull requests.
16-
17-
18- .. contents :: Contents
19- :local:
20-
21-
22- Email notifications
23- -------------------
24-
25- Read the Docs allows you to configure emails that can be sent on failing builds.
26- This makes sure you know when your builds have failed.
27-
28- Take these steps to enable build notifications using email:
18+ Configure automated feedback and documentation site previews for your pull requests.
2919
30- * Go to :guilabel: `Admin ` > :guilabel: `Notifications ` in your project.
31- * Fill in the **Email ** field under the **New Email Notifications ** heading
32- * Submit the form
33-
34- You should now get notified by email when your builds fail!
3520
3621Build status webhooks
3722---------------------
3823
39- Read the Docs can also send webhooks when builds are triggered, successful or failed.
40-
4124Take these steps to enable build notifications using a webhook:
4225
43- * Go to :guilabel : `Admin ` > :guilabel: ` Webhooks ` in your project.
26+ * Go to :menuselection : `Admin --> Webhooks ` in your project.
4427* Fill in the **URL ** field and select what events will trigger the webhook
4528* Modify the payload or leave the default (see below)
4629* Click on :guilabel: `Save `
@@ -79,6 +62,11 @@ you will see the server response, the webhook request, and the payload.
7962
8063 Activity of a webhook
8164
65+ .. note ::
66+
67+ We don't trigger :term: `webhooks <webhook> ` on :doc: `builds from pull requests </pull-requests >`.
68+
69+
8270Custom payload examples
8371~~~~~~~~~~~~~~~~~~~~~~~
8472
@@ -93,81 +81,81 @@ and in the following section you will find all the available variables.
9381
9482 Custom payload
9583
96- Slack
97- +++++
98-
99- .. code-block :: json
100-
101- {
102- "attachments" : [
103- {
104- "color" : " #db3238"
105- "blocks" : [
106- {
107- "type" : " section"
108- "text" : {
109- "type" : " mrkdwn"
110- "text" : " *Read the Docs build failed*"
84+ .. tabs ::
85+
86+ .. tab :: Slack
87+
88+ .. code-block :: json
89+
90+ {
91+ "attachments" : [
92+ {
93+ "color" : " #db3238"
94+ "blocks" : [
95+ {
96+ "type" : " section"
97+ "text" : {
98+ "type" : " mrkdwn"
99+ "text" : " *Read the Docs build failed*"
100+ }
101+ },
102+ {
103+ "type" : " section"
104+ "fields" : [
105+ {
106+ "type" : " mrkdwn"
107+ "text" : " *Project*: <{{ project.url }}|{{ project.name }}>"
108+ },
109+ {
110+ "type" : " mrkdwn"
111+ "text" : " *Version*: {{ version.name }} ({{ build.commit }})"
112+ },
113+ {
114+ "type" : " mrkdwn"
115+ "text" : " *Build*: <{{ build.url }}|{{ build.id }}>"
116+ }
117+ ]
118+ }
119+ ]
111120 }
112- },
113- {
114- "type" : " section"
115- "fields" : [
116- {
117- "type" : " mrkdwn"
118- "text" : " *Project*: <{{ project.url }}|{{ project.name }}>"
119- },
120- {
121- "type" : " mrkdwn"
122- "text" : " *Version*: {{ version.name }} ({{ build.commit }})"
123- },
124- {
125- "type" : " mrkdwn"
126- "text" : " *Build*: <{{ build.url }}|{{ build.id }}>"
127- }
128- ]
129- }
130- ]
131- }
132- ]
133- }
134-
135- the Slack Incoming Webhooks documentation <https://api.slack.com/messaging/webhooks >`_.
136-
137- Discord
138- +++++++
139-
140- .. code-block :: json
141-
142- {
143- "username" : " Read the Docs"
144- "content" : " Read the Docs build failed"
145- "embeds" : [
146- {
147- "title" : " Build logs"
148- "url" : " {{ build.url }}"
149- "color" : 15258703 ,
150- "fields" : [
151- {
152- "name" : " *Project*"
153- "value" : " {{ project.url }}"
154- "inline" : true
155- },
156- {
157- "name" : " *Version*"
158- "value" : " {{ version.name }} ({{ build.commit }})"
159- "inline" : true
160- },
161- {
162- "name" : " *Build*"
163- "value" : " {{ build.url }}"
164- }
165- ]
166- }
167- ]
168- }
121+ ]
122+ }
123+
124+ the Slack Incoming Webhooks documentation <https://api.slack.com/messaging/webhooks >`_.
125+
126+ .. tab :: Discord
127+
128+ .. code-block :: json
129+
130+ {
131+ "username" : " Read the Docs"
132+ "content" : " Read the Docs build failed"
133+ "embeds" : [
134+ {
135+ "title" : " Build logs"
136+ "url" : " {{ build.url }}"
137+ "color" : 15258703 ,
138+ "fields" : [
139+ {
140+ "name" : " *Project*"
141+ "value" : " {{ project.url }}"
142+ "inline" : true
143+ },
144+ {
145+ "name" : " *Version*"
146+ "value" : " {{ version.name }} ({{ build.commit }})"
147+ "inline" : true
148+ },
149+ {
150+ "name" : " *Build*"
151+ "value" : " {{ build.url }}"
152+ }
153+ ]
154+ }
155+ ]
156+ }
169157
170- the Discord webhooks documentation <https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks >`_.
158+ More information on `the Discord webhooks documentation <https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks >`_.
171159
172160Variable substitutions reference
173161~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -213,7 +201,7 @@ Variable substitutions reference
213201 Version name.
214202
215203Validating the payload
216- ~~~~~~~~~~~~~~~~~~~~~~
204+ ----------------------
217205
218206After you add a new webhook, Read the Docs will generate a secret key for it
219207and uses it to generate a hash signature (HMAC-SHA256) for each payload
@@ -255,7 +243,7 @@ like this:
255243 )
256244
257245
258- ~~~~~~~~~~~~~~~
246+ ---------------
259247
260248Webhooks created before the custom payloads functionality was added to Read the Docs
261249send a payload with the following structure:
0 commit comments