Solid WebhookChannel2023

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.

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:

sendTo

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.

• The type field MUST contain the type of channel being requested: WebhookChannel2023.

• The topic field MUST contain the URL of the resource to which changes a client wishes to subscribe.

• The sendTo field MUST contain the https URL of the webhook endpoint, where the notification sender is expected to send notifications.

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

• The id field MUST be a URI, which identifies the created notification channel.

• The type field MUST contain the type of channel created: WebhookChannel2023.

• The topic field MUST contain the URL of the resource which notifications will be about.

• The sender field MUST contain a URI which identifies the notifications sender.

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": ["https://www.w3.org/ns/solid/notification/v1"],
  "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": "https://www.w3.org/ns/solid/notification/v1",
  "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

• Subscription client MUST perform authenticated subscription request.

• Notification Sender MUST perform authenticated request to sendTo webhook endpoint, using identity provided as sender in the subscription response.

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].