Solid WebhookChannel2023

Editor’s Draft,

More details about this document
This version:
Issue Tracking:
Jackson Morgan
elf Pavlik


The [Solid.Notifications.Protocol] defines a set of interaction patterns for agents to receive notification about changes to resources in a Solid Storage.

This specification defines a channel type that applies these patterns to the Webhooks.

Status of this document

Version: 0.1

This section describes the status of this document at the time of its publication.

This document was published by the Solid Community Group as an Editor’s Draft. The sections that have been incorporated have been reviewed following the Solid process. However, the information in this document is still subject to change. You are invited to contribute any feedback, comments, or questions you might have.

Publication as an Editor’s Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the W3C Community Contributor License Agreement (CLA). A human-readable summary is available.

1. Introduction

This section is non-normative.

The [Solid.Notifications.Protocol] describes a general pattern by which agents can be notified when a Solid Resource changes. This specification defines a subscription type that applies these patterns to WebHooks.

1.1. Specification Goals

In addition to the goals set forth by the [Solid.Notifications.Protocol] , this specification has goals required by the WebHooks use case:

  1. Verifiable requests to a notification receiver - a notification receiver must be able to confirm if a request truly came from a specific notification sender.

  2. Unsubscribing from a WebHook - Unlike websockets, where sockets can simply be closed by the client, if a notifications receiver wants to unsubscribe from a webhook, it must alert the subscription server.

solid/notifications/155Make AuthN/AuthZ of each channel explicit
solid/notifications/145Define unsubscribing

1.2. Terminology

This section is non-normative.

This specification uses terms from the [Solid.Notifications.Protocol] specification. When Solid Notifications Protocol terminology is used it is linked directly to that specification.

2. WebhookChannel2023 Type

This specification defines the WebhookChannel2023 type for use with Solid Notifications channels that use the Webhooks.

An WebhookChannel2023 MUST conform to the Solid Notifications Protocol.

An WebhookChannel2023 SHOULD support the Solid Notifications Features.

The WebhookChannel2023 type further constrains following properties properties:


The sendTo property is used in the body of the subscription request. The value of the sendTo property MUST be a URI, using the https scheme.

A client establishes a subscription using the WebhookChannel2023 type by sending an authenticated subscription request to the Subscription Resource retrieved via Solid Notifications discovery.

For WebhookChannel2023 interactions, the subscription client sends a subscription request to an appropriate Subscription Resource. The only required fields in the payload are type, topic, and sendTo.

For WebhookChannel2023 interactions, the subscription server responds with a subscription response. The only required fields in the payload are id, type, topic, sender

solid/notifications/134Notification Sender - authentication may require both identities client & agent (user)

2.1. Subscription Example

This section is non-normative.

An example POST request, including the webhook endpoint, using a DPoP bound access token is below:

POST /subscription
Host: channels.example
Authorization: DPoP <token>
DPoP: <proof>
Content-Type: application/ld+json
  "@context": [""],
  "type": "WebhookChannel2023",
  "topic": "https://storage.example/resource",
  "sendTo": "https://webhook.example/871b84e7",
  "state": "opaque-state",
  "expiration": "2023-12-23T12:37:15Z",
  "rate": "PT10s"

POST request including type, topic, and sendTo targeting the Notification Subscription Resource.

A successful response will contain a URL identifying the notification sender:

Content-Type: application/ld+json
  "@context": "",
  "id": "https://channels.example/ea1fcf13-7482-4bbb-a6c1-c168ddd7b0aa"
  "type": "WebhookChannel2023",
  "sender": "https://sender.example/#it",
  "expiration": "2023-12-23T12:37:15Z",
  "rate": "PT10s"

Response to the POST request, including channel id, type, and sender identity.

3. Authentication and Authorization

As described by the Solid Notifications Protocol section on Authorization, the WebhookChannel2023 requires authorization and follows the guidance of the Solid Protocol sections on Authentication and Authorization [Solid.Protocol].

It is beyond the scope of this document to describe how a client fetches an access token. Solid-OIDC is one example of an authentication mechanism that could be used with Solid Notifications [Solid.OIDC].


Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Conformant Algorithms

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps can be implemented in any manner, so long as the end result is equivalent. In particular, the algorithms defined in this specification are intended to be easy to understand and are not intended to be performant. Implementers are encouraged to optimize.


Normative References

S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL:
Aaron Coburn; et al. Solid Notifications Protocol. URL:
Aaron Coburn; elf Pavlik; Dmitri Zagidulin. Solid-OIDC. URL:
Sarven Capadisli; et al. Solid Protocol. URL: