Deze pagina’s zijn in het engels ten behoeve van mogelijk internationale ontwikkelaars

This endpoint may be implemented by the following roles:

DATA SERVICE PROVIDER DATA SERVICE BROKER TRUST FRAMEWORK CATALOGUE

Subscriptions allow data service consumers to get notifications for specific events as defined by a data service provider. Within the trust framework, subscriptions are managed in phases, find more information in the lifecycle of subscriptions. The subscription resource has been defined to structure all relevant parameters of these elements and available actions throughout the lifecycle of a subscription. If data service providers decide a subscription is applicable to their situation, this must be implemented in accordance to the resources as defined here.

Data service providers MUST define subscriptions for events in accordance to the subscription resource, when implementing a subscription

Data service providers MUST define events for their subscriptions in accordance to the events resource, when implementing a subscription

Subscription resource

Parameters		Description
`id`	Required	MUST contain a unique identifier of the subscription.
`resource_type`	Required	String representing the resource type, MUST be equal to `subscription`.
`url`	Required	URL of the subscription, MUST be according to RFC3986.
`created_date`	Required	Date time when the subscription was initially created, MUST be according to ISO 8601, following the timestamp conventions.
`start_date`	Required	Contains the date time when the subscription becomes/became valid, MUST be according to ISO 8601, following the timestamp conventions.
`end_date`	Optional	If the subscription has an end date, or has ended, contains the end date and time, MUST be according to ISO 8601, following the timestamp conventions.
`consumer_id`	Required	If the subscription is assigned a data service consumer MUST contain a unique identifier of the data service consumer as an Organisation ID, containing an EORI or KvK number.
`provider_id`	Required	MUST contain a unique identifier of the data service provider as an Organisation ID, containing an EORI or KvK number.
`description`	Optional	MUST contain a human-readable description of the subscription as a string
`event_type`	Required	MUST be a list with subset of event types that is subscribed to, selected from the list defined by the data service provider
`status`	Required	MUST be the status of the subscription. Possible values are: `active`, `inactive`. See the lifecycle of a subscription for more information
`webhook_url`	Required	MUST be the URL of the data service consumer that notifications shall be sent to, according to RFC3986

Example of an subscription object

{
  "id": "sub_123",
  "resource_type": "subscription",
  "url": "/subscriptions/sub_123",
  "created_date": "2022-09-21T10:23:37Z",
  "start_date": "2022-09-21T23:59:59Z",
  "end_date": "2023-09-21T23:59:59Z",
  "consumer_id": "EU.EORI.NL000123456",
  "provider_id": "EU.EORI.NL000345678",
  "description": "detailed description of the subscription",
  "event_type": ["Modified,","Deleted"],
  "status": "active",
  "webhook_url": "https://example.com/notifications"
}

Endpoint

The /subscriptions endpoint allows data service consumers to perform a number of different functions on the subscriptions defined by a data service provider. All subscriptions APIs should follow the generic technical requirements, as well as the requirements specified for specific methods. Further, data service providers are responsible for determining a suitable authorisation policy for their subscriptions. See Autorisatie for more information.

Data service providers MUST expose their subscriptions in conformance with the DSGO /subscriptions endpoint specifications

Data service providers MUST determine suitable authorisation policy for their /subscriptions endpoint

The figure below gives an overview of the HTTP methods that are supported by the /subscriptions endpoint. These methods are further detailed and specified in the pages below: