Restore SimpliSafe event documentation (#19867)

source/_integrations/simplisafe.markdown

@@ -27,7 +27,7 @@ There is currently support for the following device types within Home Assistant:
 - **Freeze Sensor**: reports on the freeze sensor temperature*.
 - **Glass Break Sensor**: reports on the glass breakage sensor status*.
 - **Lock**: reports on `Door Locks` and can be used to lock and unlock a lock.
-- **Motion Sensor**: reports on motion detected.
+- **Motion Sensor**: reports on motion detected*.
 - **Siren**: reports on the siren status*.
 - **Smoke Detector**: reports on the smoke sensor status*.
 - **Water Sensor**: reports on water sensor status*.
@@ -67,7 +67,8 @@ entity.
 ### `simplisafe.clear_notifications`
 
 Clear any existing notifications within the SimpliSafe cloud; this will mark existing
-notifications as "read" in the SimpliSafe web and mobile apps.
+notifications as "read" in the SimpliSafe web and mobile apps, as well as prevent them
+from triggering future `SIMPLISAFE_NOTIFICATION` events.
 
 ### `simplisafe.remove_pin`
 
@@ -113,6 +114,69 @@ For any property denoting a volume, the following values should be used:
 
 ## Events
 
+### `SIMPLISAFE_EVENT`
+
+`SIMPLISAFE_EVENT` events represent events that appear on the timeline of the SimpliSafe
+web and mobile apps. When received, they come with event data that contains the
+following keys:
+
+* `changed_by`: the PIN that triggered the event (if appropriate)
+* `event_type`: the type of event
+* `info`: a human-friendly string describing the event in more detail
+* `sensor_name`: the sensor that triggered the event (if appropriate)
+* `sensor_serial`: the serial number of the sensor that triggered the event (if appropriate)
+* `sensor_type`: the type of sensor that triggered the event (if appropriate)
+* `system_id`: the system ID to which the event belongs
+* `timestamp`: the UTC datetime at which the event was received
+
+For example, when someone rings the doorbell, a
+`SIMPLISAFE_EVENT` event will fire with the following event data:
+
+```python
+{
+    "event_type": "SIMPLISAFE_EVENT",
+    "data": {
+        "last_event_changed_by": "",
+        "last_event_type": "doorbell_detected",
+        "last_event_info": "Someone is at your \"Front Door\"",
+        "last_event_sensor_name": "Front Door",
+        "last_event_sensor_serial": "",
+        "last_event_sensor_type": "doorbell",
+        "system_id": [systemid],
+        "last_event_timestamp": "2021-01-28T22:01:32+00:00"
+    },
+    "origin": "LOCAL",
+    "time_fired": "2021-01-28T22:01:37.478539+00:00",
+    "context": {
+        "id": "[id]",
+        "parent_id": null,
+        "user_id": null
+    }
+}
+```
+
+`last_event_type` can have the following values:
+
+* `automatic_test`
+* `camera_motion_detected`
+* `doorbell_detected`
+* `device_test`
+* `secret_alert_triggered`
+* `sensor_paired_and_named`
+* `user_initiated_test`
+
+To build an automation using one of these, use `SIMPLISAFE_EVENT`
+as an event trigger, with `last_event_type` as the `event_data`.
+For example, the following will trigger when the doorbell rings:
+
+```yaml
+trigger:
+  - platform: event
+    event_type: SIMPLISAFE_EVENT
+    event_data:
+        last_event_type: doorbell_detected
+```
+
 ### `SIMPLISAFE_NOTIFICATION`
 
 `SIMPLISAFE_NOTIFICATION` events represent system notifications that would appear in the