Extend webhook notifications with build status

docs/guides/build-notifications.rst

@@ -18,15 +18,15 @@ You should now get notified by email when your builds fail!
 Using webhook
 -------------
 
-Read the Docs can also send webhooks when builds fail.
+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:`Notifications` in your project.
 * Fill in the **URL** field under the **New Webhook Notifications** heading
 * Submit the form
 
-The project name, slug and its details for the build that failed will be sent as POST request to your webhook URL:
+The project name, slug and its details for the build will be sent as POST request to your webhook URL:
 
 .. code-block:: json
 
@@ -35,9 +35,11 @@ The project name, slug and its details for the build that failed will be sent as
             "slug": "rtd",
             "build": {
                 "id": 6321373,
+                "commit": "e8dd17a3f1627dd206d721e4be08ae6766fda40",
+                "state": "finished",
                 "success": false,
                 "date": "2017-02-15 20:35:54"
             }
        }
 
-You should now get notified on your webhook when your builds fail!
+You should now get notified on your webhook when your builds start and finish (failure/success)!

readthedocs/core/utils/__init__.py

@@ -14,6 +14,7 @@
 from readthedocs.builds.constants import (
     BUILD_STATE_TRIGGERED,
     BUILD_STATUS_PENDING,
+    EXTERNAL,
 )
 from readthedocs.doc_builder.constants import DOCKER_LIMITS
 
@@ -86,6 +87,7 @@ def prepare_build(
     from readthedocs.projects.tasks import (
         update_docs_task,
         send_external_build_status,
+        send_notifications,
     )
 
     build = None
@@ -142,6 +144,10 @@ def prepare_build(
             commit=commit, status=BUILD_STATUS_PENDING
         )
 
+    if build and version.type != EXTERNAL:
+        # Send Webhook notification for build triggered.
+        send_notifications.delay(version.pk, build_pk=build.pk, email=False)
+
     return (
         update_docs_task.signature(
             args=(version.pk,),

readthedocs/projects/tasks.py

@@ -428,7 +428,7 @@ def run(
                 self.setup_env.update_build(BUILD_STATE_FINISHED)
 
             # Send notifications for unhandled errors
-            self.send_notifications(version_pk, build_pk)
+            self.send_notifications(version_pk, build_pk, email=True)
             return False
 
     def run_setup(self, record=True):
@@ -489,7 +489,7 @@ def run_setup(self, record=True):
             # triggered before the previous one has finished (e.g. two webhooks,
             # one after the other)
             if not isinstance(self.setup_env.failure, VersionLockedError):
-                self.send_notifications(self.version.pk, self.build['id'])
+                self.send_notifications(self.version.pk, self.build['id'], email=True)
 
             return False
 
@@ -592,8 +592,8 @@ def run_build(self, docker, record):
                     log.warning('No build ID, not syncing files')
 
         if self.build_env.failed:
-            # TODO: Send RTD Webhook notification for build failure.
-            self.send_notifications(self.version.pk, self.build['id'])
+            # Send Webhook and email notification for build failure.
+            self.send_notifications(self.version.pk, self.build['id'], email=True)
 
             if self.commit:
                 send_external_build_status(
@@ -603,7 +603,9 @@ def run_build(self, docker, record):
                     status=BUILD_STATUS_FAILURE
                 )
         elif self.build_env.successful:
-            # TODO: Send RTD Webhook notification for build success.
+            # Send Webhook notification for build success.
+            self.send_notifications(self.version.pk, self.build['id'], email=False)
+
             if self.commit:
                 send_external_build_status(
                     version_type=self.version.type,
@@ -1065,10 +1067,10 @@ def build_docs_class(self, builder_class):
         builder.move()
         return success
 
-    def send_notifications(self, version_pk, build_pk):
+    def send_notifications(self, version_pk, build_pk, email=False):
         """Send notifications on build failure."""
         if self.version.type != EXTERNAL:
-            send_notifications.delay(version_pk, build_pk=build_pk)
+            send_notifications.delay(version_pk, build_pk=build_pk, email=email)
 
     def is_type_sphinx(self):
         """Is documentation type Sphinx."""
@@ -1613,7 +1615,7 @@ def _sync_imported_files(version, build, changed_files):
 
 
 @app.task(queue='web')
-def send_notifications(version_pk, build_pk):
+def send_notifications(version_pk, build_pk, email=False):
     version = Version.objects.get_object_or_log(pk=version_pk)
 
     if not version:
@@ -1623,11 +1625,13 @@ def send_notifications(version_pk, build_pk):
 
     for hook in version.project.webhook_notifications.all():
         webhook_notification(version, build, hook.url)
-    for email in version.project.emailhook_notifications.all().values_list(
+
+    if email:
+        for email_address in version.project.emailhook_notifications.all().values_list(
             'email',
             flat=True,
-    ):
-        email_notification(version, build, email)
+        ):
+            email_notification(version, build, email_address)
 
 
 def email_notification(version, build, email):
@@ -1703,6 +1707,8 @@ def webhook_notification(version, build, hook_url):
         'slug': project.slug,
         'build': {
             'id': build.id,
+            'commit': build.commit,
+            'state': build.state,
             'success': build.success,
             'date': build.date.strftime('%Y-%m-%d %H:%M:%S'),
         },

readthedocs/rtd_tests/tests/test_build_notifications.py

@@ -40,15 +40,15 @@ def test_send_webhook_notification(self):
 
     def test_send_email_notification(self):
         fixture.get(EmailHook, project=self.project)
-        send_notifications(self.version.pk, self.build.pk)
+        send_notifications(self.version.pk, self.build.pk, email=True)
         self.assertEqual(len(mail.outbox), 1)
 
     def test_send_email_and_webhook__notification(self):
         fixture.get(EmailHook, project=self.project)
         fixture.get(WebHook, project=self.project)
         with patch('readthedocs.projects.tasks.requests.post') as mock:
             mock.return_value = None
-            send_notifications(self.version.pk, self.build.pk)
+            send_notifications(self.version.pk, self.build.pk, email=True)
             mock.assert_called_once()
         self.assertEqual(len(mail.outbox), 1)