Use a heartbeat to allow the client to reconnect after network failures.

1 files changed, 20 insertions, 5 deletions

diff --git a/docs/api/events.md b/docs/api/events.md
index 3347a26..7fc7d78 100644
--- a/docs/api/events.md
+++ b/docs/api/events.md
@@ -86,12 +86,27 @@ The service may terminate the connection at any time. Clients should reconnect a
 
 Each event's `data` consists of a JSON object describing one event. Every event includes the following fields:
 
-| Field   | Type   | Description                                                                                                  |
-|:--------|:-------|:-------------------------------------------------------------------------------------------------------------|
-| `type`  | string | The type of entity the event describes. Will be one of the types listed in the next section.                 |
-| `event` | string | The specific kind of event. Will be one of the events listed with the associated `type` in the next section. |
+| Field   | Type             | Description                                                                                                  |
+|:--------|:-----------------|:-------------------------------------------------------------------------------------------------------------|
+| `type`  | string           | The type of entity the event describes. Will be one of the types listed in the next section.                 |
+| `event` | string, optional | The specific kind of event. Will be one of the events listed with the associated `type` in the next section. |
 
-The remaining fields depend on the `type` and `event` field.
+The remaining fields depend on the `type` and (if present) the `event` field.
+
+
+## Heartbeat events
+
+```json
+{
+  "type": "heartbeat"
+}
+```
+
+To help clients detect network interruptions, the service guarantees that it will deliver an event after a fixed interval called the "heartbeat interval." The specific interval length is given in seconds as part of the [boot response](./boot.md). If the service determines that the heartbeat interval is close to expiring, it will synthesize and deliver a heartbeat event.
+
+Clients should treat any period of time without events, longer than the heartbeat interval, as an indication that the event stream may have been interrupted. Clients may also use other techniques, such as [browser APIs](https://developer.mozilla.org/en-US/docs/Web/API/EventSource/error_event), to detect this condition and restart the connection.
+
+These events have the `type` field set to `"heartbeat"`. The `event` field is absent.
 
 
 ## User events