diff options
Diffstat (limited to 'docs/api')
| -rw-r--r-- | docs/api/events.md | 30 |
1 files changed, 30 insertions, 0 deletions
diff --git a/docs/api/events.md b/docs/api/events.md index e692f82..9db4613 100644 --- a/docs/api/events.md +++ b/docs/api/events.md @@ -237,3 +237,33 @@ These events have the `event` field set to `"deleted"`. They include the followi | :---- | :-------- | :---------------------------------- | | `at` | timestamp | The moment the message was deleted. | | `id` | string | The deleted message's ID. | + +## VAPID key events + +The following events describe changes to Pilcrow's [VAPID key](https://developer.mozilla.org/en-US/docs/Web/API/PushManager/subscribe#applicationserverkey). + +These events have the `type` field set to `"vapid"`. + +### VAPID key changed + +```json +{ + "type": "vapid", + "event": "changed", + "at": "2025-08-30T05:44:58.100206Z", + "key": "BKILjh0SzTiHOZ5P_sfduv-iqtOg_S18nR7ePcjnDivJaOY6nOG1L3OmvjXjNnthlRDdVnawl1_owfdPCvmDt5U=" +} +``` + +Sent whenever the server's VAPID key changes. + +These events have the `event` field set to `"changed"`. They include the following additional fields: + +| Field | Type | Description | +| :---- | :-------- | :----------------------------------------------------------------------------------------------- | +| `at` | timestamp | The moment the key was changed. | +| `key` | string | A URL-safe Base64 encoding of the VAPID public key, usable to create new Web Push subscriptions. | + +The server may change its VAPID key at any time, and will do so periodically to manage the risk of the private key being leaked. When the key is changed, old keys are immediately destroyed, and the corresponding change events are removed from the event stream. + +Clients must use the most recent VAPID key when creating Web Push subscriptions. If the key changes, clients must invalidate or recreate existing subscriptions - the previous key is no longer valid and will no longer be used, and push subscriptions using that key will not be fulfilled. |