13.5. PDND Signal Hub Endpoints¶

Within the PDND platform, the Signal Hub serves as an intermediary component between PDND Providers and their PDND Consumers to facilitate real-time data variation notifications. To enable this functionality, the PDND Manager, acting in the role of PDND e-Service Provider, offers the following specialized PDND Signal Hub e-Services:

the Signal Collection e-Service which is used by PDND e-Service Providers to deposit Signals, since the PDND e-Service Provider acts as Consumer of the Signal Collection e-Service;
the Signal Distribution e-Service which is used by PDND e-Service Consumers to retrieve collected Signals, since the PDND e-Service Consumer also acts as Consumer of the Signal Distribution e-Service.

In order to protect the privacy of the Signal's subject, the PDND Manager requires each PDND e-Service Provider to pseudonymize the subject's identifier used within the Signals and set up a pseudonymization endpoint for their PDND e-Service. This pseudonymization endpoint is used by e-Service Consumers to use the pseudonymization algorithm in order to calculate the Signal subject's pseudonym. Only the PDND e-Service Provider and its PDND e-Service Consumers are able to link a Signal to the subject's personal data, while the PDND Manager only handles pseudonymized identifiers.

For detailed technical specifications and implementation guidelines, please refer to the Signal Hub Guide.

In the context of the IT Wallet, Authentic Sources interact with the Signal Hub to notify Credential Issuers about changes in the status and/or value of attributes associated with Digital Credentials. Specifically,

the Authentic Source will deposit Signals in the Signal Hub, thus playing the role of PDND Consumer of the Signal Collection e-Service;
the Credential Issuer will retrieve Signals from the Signal Hub, and will thus play the role of PDND e-Service Consumer of the Signal Distribution e-Service.

Note

In the context of IT Wallet, due to the particular nature of the data exchanged, the pseudonymization of the Signal's subject is not needed since it is already an opaque identifier unrelated to the Digial Credential's subject. Thus, the Authentic Source does not need to set up a pseudonymization endpoint for its e-Services.

Authentic Sources that leverage PDND MUST use the Signal Hub e-Services.

Below it is provided the description of how the Authentic Sources and Credential Issuers interact with the Signal Hub e-Services together with the detailed formats of the requests and responses.

13.5.1. Prerequisites¶

Before using the Signal Hub, all Authentic Sources MUST:

have registered as Providers of their e-Service with the PDND;

have registered as Consumers of the Signal Collection e-Service of the Signal Hub;

Before using the Signal Hub, all Credential Issuers MUST:

have registered as Consumers of the relevant Authentic Sources' e-Services;

have registered as Consumers of the Signal Distribution e-Service of the Signal Hub;

13.5.2. Signal Hub e-Services¶

This section describes the endpoints available for the Signal Hub Collection and Distribution e-Services, including their functionalities and the expected request and response formats.

13.5.2.1. Signal Collection e-Service¶

Authentic Sources in the IT Wallet ecosystem use the Signal Collection e-Service to:

notify the Credential Issuer of a change of status and/or value of a specific attribute associated with a Digital Credential issued by the Credential Issuer;

notify the Credential Issuer of the availability of the attributes related to a specific Digital Credential which a User requested in its Wallet.

The last case, referred to as deferred issuance, happens when the Credential Issuer has requested a Digital Credential's attributes from the Authentic Source (invoking the Get Attribute Claims PDND endpoint) and the Authentic Source cannot respond immediately with the requested attributes. Thus, the Authentic Source notifies the Credential Issuer via the Signal Hub at a later time that the requested attributes are now available.

The Signal Collection e-Service endpoint is used by Authentic Sources to deposit Signals to the Signal Hub via a Signal Collection request. The latter MUST be a POST request with Content-Type set to application/json, whose header MUST have the parameters described in Signal Hub Guide and whose body MUST contain the following parameters:

Parameter Name	Description
signalId	REQUIRED. A positive 64 bit integer number referencing the identifier of the Signal in chronological order.
objectType	REQUIRED. Using this field the Authentic Source MAY use to further specify the Signal.
objectId	REQUIRED. The subject to which the Signal is bound. If the Signal has `signalType`: `CREATE`, then it MUST be set to the `jti` value the Credental Issuer used in the Agid-JWT-Signature token of the get attributes request to the Authentic Source to obtain the attributes related to a specific Digital Credential (see Get Attribute Claims); `UPDATE`, then it MUST be set to the Authentic Source's unique database identifier of the Digital Credential's attributes the Signal refers to.
signalType	REQUIRED. Signal Type. It MUST be one of the following: `UPDATE`, when the Signal refers to a change in the status and/or value of a specific attribute associated with a Digital Credential; `CREATE`, when the Signal refers to the availability of the attributes of a specific Digital Credential;
eserviceId	REQUIRED. e-Service to which the Signal is bound. It MUST correspond to the e-Service Id value the Authentic Source is a Provider of.

Note

In the deffered issuance flow, i.e., when the Authentic Source notifies the Credential Issuer of the availability of the Digital Credential's attributes via Signal Hub; both entities MUST keep track of the Credential Issuer's jti value used in the Agid-JWT-Signature of the get attributes request. This is necessary since the objectId of the Signal MUST be set to that jti value when the Signal has signalType with value CREATE.

A non normative example of the Signal Collection request can be found at Signal Hub push.

The Signal Collection e-Service response, acknowledging the correct parsing of the request, is specified in Signal Hub push, and has Content-Type set to application/json. The payload contains the body parameter:

Parameter Name	Description
signalId	REQUIRED. The identifier of the Signal that has been successfully collected by the Signal Collection e-Service.

If any error occurs during the request parsing, the response MUST adhere to the error format defined in Signal Hub push-yaml.

Note

A complete OpenAPI Specification of the Signal Collection e-Service is available Signal Hub push-yaml.

The Authentic Source MUST implement the necessary logic to handle the requests to the Signal Collection e-Service endpoint, in doing this it has to consider the following aspects:

Signals are sent per PDND e-Service, therefore the Authentic Source SHOULD implement a Signal deposit cycle for each e-Service ID it is a PDND Provider of;

Signals are labeled by a unique identifier, the signalId, which is a positive 64 bit integer number. The signalId MUST be incremented by 1 for each new Signal the Authentic Source wishes to deposit in the Signal Collection e-Service endpoint. It is up to the Authentic Source to keep track of the last signalId it has sent. Signals with lower signalId values are considered older by the Signal Collection e-Service endpoint and raise an error when received.

13.5.2.2. Signal Distribution e-Service¶

Credential Issuers in the IT Wallet ecosystem use the Signal Distribution e-Service to:

check for changes in the status and/or value of a specific attribute associated with a Digital Credential issued by the Credential Issuer itself;

check for the availability of attributes related to a Digital Credential requested by a User.

The Signal Distribution e-Service endpoint is used by Credential Issuers to retrieve Signals from the Signal Hub via a Signal Distribution request. The latter MUST use an HTTP request using the method GET and the following parameters:

Path Parameters:

eserviceId. REQUIRED. e-Service to which the Signal is bound. It MUST correspond to the e-Service Id value the Credential Issuer is a Consumer of.

Query Parameters:

signalId. OPTIONAL. Integer representing the last Signal number processed by the Credential Issuer. The Signal Distribution e-Service will respond with Signals having progressively greater signalId values. If not specified, the default value is the lowest signalId value available in the Signal Distribution e-Service.

size. OPTIONAL. Integer representing the maximum number of Signals to be returned in the Signal Distribution response. If not specified, the default value is 10.

Headers parameters: these are those described in Signal Hub pull.

If the Signal Distribution request is correctly processed, the e-Service will then respond with status code

HTTP 200 OK if the request is correctly formed and there are no more Signals to request;

HTTP 206 OK if the request is correctly formed but there are more Signals to request.

Regardless of the response code used, the response has Content-Type set to application/json an the header parameters indicated in Signal Hub pull. The body parameter lastSignalId, referencing the signalId of the last Signal transmitted by the Signal Distribution e-Service is added to the response's payload.

In Signal Hub pull can be found non normative examples of a Signal Distribution requests and responses.

If any error occurs during the request parsing, the response MUST adhere to the error format defined in Signal Hub pull-yaml.

Note

A complete OpenAPI Specification of the Signal Collection e-Service is available Signal Hub pull-yaml.

The Credential Issuer MUST implement the necessary logic to handle the Polling of the Signal Distribution e-Service endpoint, in doing this it has to consider the following aspects:

Signals are queried and retrieved per PDND e-Service, meaning that the Credential Issuer MUST implement a poll cycle for each e-Service ID;

the retention period of Signals in the Signal Hub is specified in Signal Hub Guide. Signals older than the specified retention period are not available for retrieval;

the Signal Hub does not keep track of the last signalId notified to a specific Credential Issuer. Each Credential Issuer MUST keep track of the last signalId it has received for each PDND e-Service ID;

the Signal Distribution e-Service endpoint returns Signals in batches. The maximal size the batch is specified in Signal Hub Guide. The Signal Distribution e-Service will indicate if additional Signals are available for retrieval.

13.5.3. Signals Processing¶

After the Signals have been successfully recovered by the Credential Issuer, the latter MUST process them as follows:

For each Signal, the Credential Issuer MUST check the SignalType value:

if the Signal SignalType is UPDATE, the status and/or value of the attribute associated with a Digest Credential need updates;

if the Signal SignalType is CREATE, the requested attributes of a specific Digital Credential are now available;

If the objectId does not correspond to any valid identifier known to the Credential Issuer, the Signal MUST be ignored. Otherwise, if it corresponds to a known and valid identifier, the Credential Issuer MUST use the Get Attribute Claims PDND endpoint of the Authentic Source to retrieve the updated information and, if applicable, apply the new status to the corresponding Credential.

When the Signal has been processed, the Credential Issuer will either move to the next Signal and update its signalId counter; or, if there are no more Signals to process, it will resume the Pull cycle.

Warning

Given Signal Hub's currently supported security patterns, if the Authentic Source requires the AUDIT_REST_02 security pattern from the Credential Issuer, the latter MUST revoke the Digital Credential referenced in Signals with signalType UPDATE since it cannot contact the Authentic Source to retrieve the updated information without having authenticated the User before.