Envelope Properties

A notification envelope has the following properties:

• type — REQUIRED. The value MUST be the string Notification.
• phase — OPTIONAL. A string indicating at which point in the resource lifecycle the notification was emitted. This specification defines the value PostCommit, which indicates that the described change has already been persisted.
• storage — REQUIRED. A URI identifying the LWS storage with which the notification is associated.
• activity — REQUIRED. A JSON object or an array of JSON objects, each conforming to the Activity Streams 2.0 data model, describing the event or events that occurred. See .

{
  "@context": [
    "https://www.w3.org/ns/lws/v1",
    "https://www.w3.org/ns/activitystreams"
  ],
  "type": "Notification",
  "phase": "PostCommit",
  "storage": "https://storage.example/",
  "activity": {
    "id": "ec4dcc48-6581-4232-81c9-584525a98693",
    "type": ["Delete"],
    "object": {
      "id": "https://storage.example/alice/notes/shopping.txt",
      "type": ["DataResource"]
    },
    "origin": "https://storage.example/alice/notes/",
    "published": "2026-03-26T10:30:00Z"
  }
}
        

Activity Properties

Each activity object within the activity property MUST conform to the Activity Streams 2.0 data model and MUST include the following properties:

• id — REQUIRED. A string uniquely identifying the activity.
• type — REQUIRED. An array of strings containing at least one Activity Streams 2.0 activity type.
• object — REQUIRED. A JSON object identifying the resource that the notification is about. The object MUST include the following properties:
  • id — REQUIRED. The URI of the resource.
  • type — REQUIRED. An array of strings containing at least one resource type. Values defined by [[!LWS-PROTOCOL]] include Container and DataResource. Additional type values MAY be included.
• published — REQUIRED. A datetime value conforming to [[!RFC3339]] indicating when the activity occurred.

The following properties are OPTIONAL:

• actor — a URI identifying the agent that performed the action.
• target — a URI identifying the container into which the resource was added. Used with Create activities.
• origin — a URI identifying the container from which the resource was removed. Used with Delete activities.

Activity Types

A server MUST support the following Activity Streams 2.0 activity types to indicate LWS resource changes:

• Create — a new resource was created in a container. The target field indicates the container to which the resource was added.
• Update — an existing resource's content or metadata was modified.
• Delete — a resource was removed. The origin field indicates the container from which the resource was removed.

Other activity types MAY also be supported.

Batching Notifications

A server MAY combine multiple activities into a single notification envelope by providing an array of activity objects as the value of the activity property.

{
  "@context": [
    "https://www.w3.org/ns/lws/v1",
    "https://www.w3.org/ns/activitystreams"
  ],
  "type": "Notification",
  "phase": "PostCommit",
  "storage": "https://storage.example/",
  "activity": [
    {
      "id": "a1b2c3d4-5678-9abc-def0-1234567890ab",
      "type": ["Create"],
      "object": {
        "id": "https://storage.example/alice/notes/meeting.txt",
        "type": ["DataResource"]
      },
      "target": "https://storage.example/alice/notes/",
      "published": "2026-03-26T10:30:00Z"
    },
    {
      "id": "b2c3d4e5-6789-abcd-ef01-234567890abc",
      "type": ["Update"],
      "object": {
        "id": "https://storage.example/alice/profile",
        "type": ["DataResource"]
      },
      "published": "2026-03-26T10:30:01Z"
    }
  ]
}
        

Subscription Request

A subscription request MUST contain the following fields:

• type — REQUIRED. A string identifying the subscription type. The value MUST be one of the types listed in the subscriptionType array of the NotificationService.
• topic — REQUIRED. An array of URIs identifying the resources included in the subscription.

A subscription request MAY contain the following fields:

• phase — OPTIONAL. A string indicating the lifecycle phase for which notifications are requested. This specification defines the value PostCommit.

A subscription request MAY contain additional fields as required by the specific subscription type.

POST /subscriptions HTTP/2
Host: notification.example
Authorization: Bearer <access-token>
Content-Type: application/lws+json

{
  "@context": ["https://www.w3.org/ns/lws/v1"],
  "type": "EventSourceSubscription",
  "phase": "PostCommit",
  "topic": [
    "https://storage.example/alice/notes/",
    "https://storage.example/alice/profile"
  ]
}
        

Subscription Scope

A subscription to a container is recursive: the subscriber receives notifications for the container itself and for all resources transitively contained in that container. A subscription to a data resource applies only to that individual resource.

Subscription Authorization

A server MUST enforce resource authorization when creating a subscription. If a subscriber does not have the equivalent of read access to all resources listed in the topic array, the server MUST reject the subscription request.

Authorization MUST also be enforced at notification delivery time. A server MUST NOT deliver a notification about a resource that the subscriber is not authorized to read at the time the event occurs. This applies to all resources within the scope of a subscription, including resources in subcontainers.

If the subscriber's access to a resource or container within the scope of a subscription is revoked after the subscription is created, the server MUST stop delivering notifications for the affected resources. The server SHOULD NOT terminate the entire subscription unless the subscriber has lost access to all resources in the topic array.

Subscription-time authorization verifies that a subscriber has a legitimate basis for receiving notifications. Delivery-time authorization ensures that notifications remain consistent with the subscriber's current permissions, accounting for authorization changes that may occur after the subscription was created.

Subscription Response

The response to a successful subscription creation request MUST conform to the application/lws+json media type and MUST contain the following fields:

• type — REQUIRED. A string equal to the subscription type from the request.
• subscription — REQUIRED. A URL representing the subscription.

Creating a WebSocket Subscription

When a client creates a WebSocket notification subscription, the subscription body MUST include a type field equal to WebSocketSubscription.

A successful response body has these additional requirements:

• type — the value of this property MUST be a string equal to WebSocketSubscription.
• subscription — the value of this property MUST be a capability URL that can be used by the WebSocket API.

{
  "@context": ["https://www.w3.org/ns/lws/v1"],
  "type": "WebSocketSubscription",
  "subscription": "wss://notification.example/ws/1c2d3e4f5a6b"
}
        

Establishing a WebSocket Connection

After obtaining a capability URL, the subscriber opens a WebSocket connection to that URL. The server sends notification envelopes as WebSocket text messages, serialized as JSON.

const ws = new WebSocket(capabilityUrl);
ws.onmessage = (event) => {
  const notification = JSON.parse(event.data);
  // handle notification
};
        

The lifecycle of a WebSocket subscription is tied to the connection. When the WebSocket connection is closed, the subscription is terminated.

Creating an EventSource Subscription

When a client creates an EventSource notification subscription, the subscription body MUST include a type field equal to EventSourceSubscription.

A successful response body has these additional requirements:

• type — the value of this property MUST be a string equal to EventSourceSubscription.
• subscription — the value of this property MUST be a capability URL that can be used by the EventSource API.

{
  "@context": ["https://www.w3.org/ns/lws/v1"],
  "type": "EventSourceSubscription",
  "subscription": "https://notification.example/sse/0d8b4c2e1a3f"
}
        

Establishing an EventSource Connection

After obtaining a capability URL, the subscriber establishes a persistent SSE connection to that URL. The server responds with Content-Type: text/event-stream and pushes notification envelopes as events. Each event MUST include an id field to support reconnection via the Last-Event-ID header.

const source = new EventSource(capabilityUrl);
source.onmessage = (event) => {
  const notification = JSON.parse(event.data);
  // handle notification
};
        

The lifecycle of an EventSource subscription is tied to the connection. When the connection is closed, the subscription is terminated.

Creating a Webhook Subscription

When a client creates a webhook notification subscription, the subscription body MUST include a type field equal to WebhookSubscription. In addition, a server MUST support the following fields:

• inbox — REQUIRED. The URI of the inbox to which notification messages are delivered.
• expires — OPTIONAL. A datetime value indicating when the subscription expires.

POST /subscriptions HTTP/2
Host: notification.example
Authorization: Bearer <access-token>
Content-Type: application/lws+json

{
  "@context": ["https://www.w3.org/ns/lws/v1"],
  "type": "WebhookSubscription",
  "phase": "PostCommit",
  "topic": [
    "https://storage.example/alice/notes/",
    "https://storage.example/alice/profile"
  ],
  "inbox": "https://receiver.example/hooks/lws",
  "expires": "2026-06-09T12:00:00Z"
}
        

A successful response body has these additional requirements:

• type — the value of this property MUST be a string equal to WebhookSubscription.
• subscription — a URL that can be used to manage the lifecycle of the subscription.
• expires — OPTIONAL. A datetime value indicating when the subscription expires.

HTTP/2 200 OK
Content-Type: application/lws+json
Location: https://notification.example/subscriptions/9e8d7c6b5a4f

{
  "@context": ["https://www.w3.org/ns/lws/v1"],
  "type": "WebhookSubscription",
  "subscription": "https://notification.example/subscriptions/9e8d7c6b5a4f",
  "expires": "2026-06-09T12:00:00Z"
}
        

Webhook Authentication

When a server delivers a notification to an inbox, the subscriber needs to verify that the request is authentic.

A server SHOULD sign each outbound request using HTTP Message Signatures [[!RFC9421]]. When an inbox receives a signed message, it MUST verify the signature using the notification server's public key, discoverable via the storage description resource.

A server that supports HTTP Message Signatures MUST include the signing key in the storage description resource. The key MUST be expressed as a verification method in a verificationMethod array, and MUST be referenced from an authentication verification relationship, following the Controlled Identifiers 1.0 [[!CID-1.0]] data model.

{
  "@context": ["https://www.w3.org/ns/lws/v1"],
  "id": "https://storage.example/",
  "type": "Storage",
  "verificationMethod": [{
    "id": "https://storage.example/#key-20260320",
    "type": "JsonWebKey",
    "controller": "https://storage.example/",
    "publicKeyJwk": {
      "kid": "key-20260320",
      "kty": "EC",
      "crv": "P-256",
      "alg": "ES256",
      "x": "f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
      "y": "x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0"
    }
  }],
  "authentication": ["https://storage.example/#key-20260320"],
  "service": [{
    "type": "NotificationService",
    "serviceEndpoint": "https://notification.example/subscriptions",
    "subscriptionType": ["WebhookSubscription"]
  }]
}
        

Subscription Management

The value of the serviceEndpoint property for a NotificationService that supports WebhookSubscription MUST be a URL that supports GET operations to list a subscriber's active webhook subscriptions. The resulting serialization MUST conform to the requirements for LWS Containers [[!LWS-PROTOCOL]]. The response SHOULD support LWS Paging.

Each subscription resource listed in this container MUST support GET and DELETE operations. A GET request returns the current state of the subscription. A DELETE request cancels the subscription.

Notification Delivery

The server sends an HTTP POST request to the registered inbox with the notification envelope as the request body. The request body MUST conform to the application/lws+json media type.

• Acknowledgment: A 2xx response indicates successful receipt.
• Retry: On failure, the server MAY retry delivery.
• Expiration: After repeated failures, the server MAY deactivate the subscription.