diff --git a/source/_components/downloader.markdown b/source/_components/downloader.markdown
index 53063587d69..469c13d2b79 100644
--- a/source/_components/downloader.markdown
+++ b/source/_components/downloader.markdown
@@ -42,3 +42,29 @@ This will download the file from the given URL.
 | `subdir`               |      yes | Download into subdirectory of **download_dir** |
 | `filename`             |      yes | Determine the filename.                        |
 | `overwrite`            |      yes | Whether to overwrite the file or not, defaults to `false`. |
+
+### {% linkable_title Download Status Events %}
+
+When a download finished successfully, Home Assistant will emit a 'downloader_download_completed' event to the event bus which you can use to write automations against.
+In case download failed another event 'downloader_download_failed' is emitted to indicate that the download did not complete successfully.
+
+Along with the event the following payload parameters are available:
+
+| Parameter | Description                                                                                                                                                                                                                                                    |
+|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `url`  | The `url` that was requested.|                                                                                                                                      
+| `filename`    | The `name` of the file that was being downloaded.|
+
+#### Example Automation:
+
+```yaml
+- alias: Download Failed Notification
+  trigger:
+    platform: event
+    event_type: downloader_download_failed
+  action:
+    service: persistent_notification.create
+    data_template:
+      message: "{{trigger.event.data.filename}} download failed"
+      title: "Download Failed"
+ ```