Push subscriptions to CREODIAS EODATA catalogue
Push and pull subscriptions allow you to receive notifications when products in EODATA catalogue (or a subset of such products) are added, modified, or deleted.
In this article, we discuss push subscriptions, which are the subscriptions that push notifications directly to an endpoint managed by the user.
There are also the so-called pull subscriptions, which are a method of receiving notifications from the CREODIAS EODATA catalogue by periodically retrieving them from a dedicated cloud-based queue. They are covered in Pull subscriptions to CREODIAS EODATA catalogue.
Prerequisites
No. 1 Account
You need an active CREODIAS account https://new.cloudferro.com/.
No. 2 Ability to send HTTP requests
To follow this article, you need to have a method of sending the following types of HTTP requests:
GET
POST
PATCH
DELETE
including corresponding headers and bodies. You also need to be able to read responses to these requests.
This article will include Python in two optional examples. Aside from these, the content remains “software-neutral.” The focus of the article is not on Python itself, but on HTTP requests, which you can send using any software of your choice:
curl, wget, httpie, JavaScript Fetch API, Axios (Node.js), Netcat/nc, PowerShell Invoke-RestMethod, Go (net/http), Java (HttpClient) and so on.
No. 3 Running Python code (optional)
You should have some experience using Python in order to run the above mentioned examples. Basics of Python are outside of scope of this article.
Apart from that, you will need to have Python and requests module installed.
If you are using Ubuntu 24.04, execute
sudo apt install python3-requests
to install the required requests module. This should also install Python interpreter if you don’t have it yet.
On Windows, you can follow this article How to install Python in Windows on CREODIAS. After that, install the requests module.
Other operating systems might also work, but adjustments might be required.
No. 4 Knowledge how to filter products
If you want to be notified about changes to only a subset of products (as opposed to receiving data for all products), you need to use the appropriate filter.
Filters used in this article are described in EOData Catalogue API Manual on CREODIAS (they are the same as the ones used for $filter parameter for OData).
For filters regarding created and/or modified products, check section about Products OData endpoint in EODATA Catalogue API Manual article.
For filters regarding deleted products, check section about DeletedProducts OData endpoint in EODATA Catalogue API Manual article.
Products and DeletedProducts endpoints differ when it comes to available options, for example, the DeletedProducts allows you to search by cause of deletion of EODATA products while for Products endpoint there is no equivalent option.
No. 5 Generated Keycloak token
To prove your identity while using pull subscriptions, you need a Keycloak token. Here is how to generate it: Using curl and wget to download EODATA products from CREODIAS
Keycloak token is valid only for a limited time; you can generate new token if the current one expires and you want to continue using the subscriptions API.
If you are using Python or Bash and two-factor authentication is enabled on your account, you can also generate Keycloak token automatically without having to provide six-digit TOTP code. Learn more:
No. 6 Endpoint which will receive notifications
You need to have physical or virtual machine which will serve as your endpoint. It needs to have a public IP address and a domain attached to it. You also need an open port to which the notifications will be sent.
To read incoming notifications, you need to have HTTP server software with support for Basic Authentication. It must be secured via HTTPS, with a certificate provided by a trusted entity. This entity can be, for instance, one of the commercial providers, or Let’s Encrypt (which provides free certificates).
You can configure such a server on, among others, a Linux virtual machine running on CREODIAS cloud which has a Floating IP attached to it.
Introduction
What should a HTTP request contain?
You can create and manage your push subscriptions by sending HTTP requests.
When sending HTTP requests described in this article, always use:
Type of request (GET, POST, PATCH or DELETE)
Headers
URL
All these three parts of a HTTP request must be present together. Certain types of HTTP requests must also contain a body.
Headers
Requests in this article should contain the following headers:
{
"Content-Type": "application/json",
"Authorization": "Bearer <<access_token>>"
}
where <<access_token>> needs to be replaced with Keycloak token from Prerequisite No. 5. This token will be used to prove your identity.
We will call them “the obligatory headings” and will refer to them as such throughout the article.
JSON data in respones
Some requests described in this article return JSON data. For the purposes of this article, we formatted them as multiple lines so that they are more legible.
Push subscription entity description
Property name | Type | Description |
---|---|---|
Id | Guid |
It is a universally unique identifier (UUID). The Id is a local identifier for a Subscription instance within the Catalogue, assigned upon Subscription creation.
Example 9249dde5-4838-4a34-8925-bac8c1d53f09c |
Status | Subscription Status enumeration |
The allowed values of a subscription status are:
Example running |
SubscriptionEvent | Subscription Event enumeration |
The subscription event to be monitored and for which a notification is provided. Can have the following values:
For "SubscriptionEvent" = "created" the notifications about newly added products to the EOData Catalogue will be sent. For "SubscriptionEvent" = "modified" the notifications about updated products in the EOData Catalogue will be sent. For "SubscriptionEvent" = "deleted" the notifications about removed products from the EOData Catalogue will be sent. This will happen if one of the following values of the "DeletionCause" parameter is met:
Example created |
FilterParam | String |
The filter parameters of the Subscription.
If "SubscriptionEvent" = "created" or "modified", this query refers to the $filter= parameter of any Products? query. If "SubscriptionEvent" = "deleted", this query refers to $filter= parameter of any DeletedProducts query. The same filtering parameters as described for EOData Catalogue are available - see Prerequisite No. 3 for more details. Example Collection/Name eq 'SENTINEL-1' and Attributes/OData.CSC.StringAttribute/any (att:att/Name eq 'productType' and att/OData.CSC.StringAttribute/Value eq 'IW_SLC__1S') |
SubmissionDate | DateTimeOffset |
Date and time at which the Subscription was received by the Catalogue. Time is in ISO 8601 format (UTC+0): YYYY-MMDDThh:mm:ss.sssZ
Example 2024-01-17T09:13:04.654Z |
LastNotificationDate | DateTimeOffset |
Date and time corresponding to the last time the Subscription Service successfully sent a notification to the user's endpoint. Time is in ISO 8601 format (UTC+0): YYYY-MMDDThh:mm:ss.sssZ
Example 2024-01-17T09:50:10.654Z |
StageOrder | Boolean |
Automatically orders the staging of products fulfilling the subscription. Only used if value of SubscriptionEvent is created. Currently, the order of staging products is not feasible as all products in EOData Catalogue have status set to Online and can be accessed immediately without setting order. Example true |
Priority | Int64 |
Priority of the created orders resulting from the subscription. Currently automatically set to 1 without the possibility to change the value.
Example 1 |
NotificationEndpoint | String |
User's endpoint to which the notifications will be sent.
Example https://notification-endpoint.example.com:4000 |
NotificationEpUsername | String |
The username used to authenticate to notification endpoint. It is mandatory if NotificationEndpoint requires authentication. Example mylocalusername |
NotificationEpPassword | String |
The password used to authenticate to notification endpoint. It is mandatory if NotificationEndpoint requires authentication. Example My%Password#789 |
Limitations of subscriptions
Your account can only have up to 2 (two) running subscriptions at the same time. These can either be
two push subscriptions: (which are described in this article), or
two pull subscriptions (which are described in doc:/eodata/Pull-subscriptions-to-Creodias-EODATA-catalogue), or
a push subscription and a pull subscription.
The maximum total number of subscriptions associated with a CREODIAS account is 10. This includes subscriptions of all types:
running and paused
push and pull
Creating push subscription
This is a typical body of request to create a push subscription:
{
"StageOrder": true,
"FilterParam": "Collection/Name eq 'SENTINEL-1' and Attributes/OData.CSC.StringAttribute/any(att:att/Name eq 'productType' and att/OData.CSC.StringAttribute/Value eq 'IW_SLC__1S')",
"Priority": 1,
"Status": "running",
"SubscriptionEvent": [
"created"
],
"NotificationEndpoint": "https://example.com:8000/",
"NotificationEpUsername": "NotificationEndpointUser",
"NotificationEpPassword": "My@!Passw0rd"
}
Set up your own values to the following six keys in that JSON body:
- SubscriptionEvent
Value of this key is an array containing only one string. With this string, you choose which types of events do you wanted to be notified about. It can have one of the following values:
created
modified
created, modified
deleted
- FilterParam
Replace the value of key FilterParam with query which defines subset of products about which you want to be notified. See Prerequiste No. 4 to learn more.
To get information
about created and/or modified products, use the same query as you would send to Products endpoint
about deleted products, use the same query as you would send to DeletedProducts endpoint
You can also get notifications about selected types of events associated with all products from the catalogue, not only a subset of them. To that end, you can either
leave the value of key FilterParam empty, or
do not include that key with your request at all.
- Status
If you set value of this key to running, the created subscription will immediately start receiving notifications. If you, however, want to create a paused (inactive) subscription and activate it later, set this value to paused.
If you do not add this key to your request, the created subscription will have running status.
If you already have 2 running subscriptions and you attempt to create another subscription with the same status, this operation will fail. See section Limitations of subscriptions above for more details.
To resolve, you can either
pause one of your current subscriptions and then create a new subscription, or
create a new subscription with paused status.
- NotificationEndpoint
The URL of your endpoint, alongside with the port under which it is available.
- NotificationEpUsername
The username used to authenticate on your notification endpoint.
- NotificationEpPassword
The password used to authenticate on your notification endpoint.
You can also get notifications about all products published in the catalogue, not only a subset of them. To that end, you can either
leave the value of key FilterParam empty, or
do not include that key with your request at all.
NotificationEpUsername and NotificationEpPassword should be secure and not the same as credentials used for your CREODIAS account.
Query provided as value of key FilterParam in example above should be valid, so you can use it to test push notifications.
REMINDER: Include the obligatory headers.
This is the URL to which you should send this request:
https://datahub.creodias.eu/odata/v1/Subscriptions
Response code to that request should be 201 Created. You should also get JSON data which contain information about your new subscription, for example:
{
"Id": "0b5aaa72-922f-4b69-ad7f-1ccebc3e824e",
"FilterParam": "Collection/Name eq 'SENTINEL-1' and Attributes/OData.CSC.StringAttribute/any(att:att/Name eq 'productType' and att/OData.CSC.StringAttribute/Value eq 'IW_SLC__1S')",
"StageOrder": false,
"Priority": 1,
"Status": "running",
"NotificationEndpoint": "https://example.com:8000/",
"SubscriptionEvent": [
"created"
],
"SubmissionDate": "2025-04-10T10:35:51.299345Z",
"@odata.context": "$metadata#OData.CSC.Subscription"
}
The subscription should now have been created.
Example: Creating push subscription using Python
Here is the code in Python that will send a request with the parameters described as above:
import requests
import json
access_token = ""
headers = {
"Content-Type": "application/json",
"Authorization": f"Bearer {access_token}",
}
body = {
"StageOrder": True,
"FilterParam": "Collection/Name eq 'SENTINEL-1' and Attributes/OData.CSC.StringAttribute/any(att:att/Name eq 'productType' and att/OData.CSC.StringAttribute/Value eq 'IW_SLC__1S')",
"Priority": 1,
"Status": "running",
"SubscriptionEvent": [
"created"
],
"NotificationEndpoint": "https://example.com/catalogue-notifications:8000",
"NotificationEpUsername": "NotificationEndpointUser",
"NotificationEpPassword": "My@!Passw0rd"
}
url = "https://datahub.creodias.eu/odata/v1/Subscriptions"
response = requests.post(url=url, headers=headers, json=body)
print(f"{response.status_code} {response.reason}\n")
try:
print(json.dumps(json.loads(response.text), indent=4))
except Exception:
print(response.text)
This script:
Sends an HTTP request to the specified URL.
Retrieves and displays the results, which consist of:
The response status code (e.g., 200) and reason (e.g., OK).
A blank lane (for readibility).
Response code, if present. (If it is a valid JSON, it will be formatted to make it more legible.)
Note that in this script, the request body is sent to the requests module using json parameter.
Assign Keycloak token obtained by following Prerequisite No. 5 to variable access_token.
In dictionary body, enter information about notification as values of appropriate keys:
NotificationEndpoint - URL of notification endpoint, including port if it is not 443
NotificationEpUsername - username for your endpoint
NotificationEpPassword - password to your endpoint
Save the file as http_request_test_create.py
To run this script, execute the following command (assuming you are in the same folder as the script):
python3 http_request_test_create.py
python http_request_test_create.py
Example: Creating a subscription to track created and modified products
In this example, we will create a subscription which tracks both created and modified products that meet the following criteria (FilterParam):
Collection/Name eq 'SENTINEL-1' and Attributes/OData.CSC.StringAttribute/any(att:att/Name eq 'productType' and att/OData.CSC.StringAttribute/Value eq 'IW_SLC__1S')
To do it, send POST HTTP request with the following body:
{
"StageOrder": true,
"FilterParam": "Collection/Name eq 'SENTINEL-1' and Attributes/OData.CSC.StringAttribute/any(att:att/Name eq 'productType' and att/OData.CSC.StringAttribute/Value eq 'IW_SLC__1S')",
"Priority": 1,
"Status": "running",
"SubscriptionEvent": [
"created, modified"
],
"NotificationEndpoint": "https://example.com/catalogue-notifications:8000",
"NotificationEpUsername": "NotificationEndpointUser",
"NotificationEpPassword": "My@!Passw0rd"
}
to this URL:
https://datahub.creodias.eu/odata/v1/Subscriptions
REMINDER: Include the obligatory headers.
You should get status code 201 Created and the following JSON object:
{
"Id": "6d73b84b-93c6-42aa-8c87-036585cfce04",
"FilterParam": "Collection/Name eq 'SENTINEL-1' and Attributes/OData.CSC.StringAttribute/any(att:att/Name eq 'productType' and att/OData.CSC.StringAttribute/Value eq 'IW_SLC__1S')",
"StageOrder": false,
"Priority": 1,
"Status": "running",
"NotificationEndpoint": "https://example.com/catalogue-notifications:8000",
"SubscriptionEvent": [
"created",
"modified"
],
"SubmissionDate": "2025-04-10T12:01:29.231216Z",
Example: Attempting to create a subscription with using invalid FilterParam
Let’s say that we accidentally attempted to create a subscription with an invalid query, for example, by using Colection/Name instead of Collection/Name:
Colection/Name eq 'SENTINEL-1' and Attributes/OData.CSC.StringAttribute/any(att:att/Name eq 'productType' and att/OData.CSC.StringAttribute/Value eq 'IW_SLC__1S')
The body of the request which we will send contains our invalid query:
{
"StageOrder": true,
"FilterParam": "Colection/Name eq 'SENTINEL-1' and Attributes/OData.CSC.StringAttribute/any(att:att/Name eq 'productType' and att/OData.CSC.StringAttribute/Value eq 'IW_SLC__1S')",
"Priority": 1,
"Status": "running",
"SubscriptionEvent": [
"created"
],
"NotificationEndpoint": "https://example.com/catalogue-notifications:8000",
"NotificationEpUsername": "NotificationEndpointUser",
"NotificationEpPassword": "My@!Passw0rd"
}
As previously, we send our request to the following URL:
https://datahub.creodias.eu/odata/v1/Subscriptions
As a response, we get response code 400 Bad Request and the following JSON data:
{
"detail": "Your filter is incorrect. We suggest to verify it with catalogue API. Detailed error message -> Invalid field: Colection"
}
This response will vary depending on the type of error you make in your query.
What happens after a push subscription has been created?
If your HTTP request was successful, a subscription should be created.
If that subscription is active, your notification endpoint (see Prerequisite No. 6) will receive a notification each time a relevant event occurs. This notification will include details about the product associated with the event.
An example notification is too long to be published verbatim in this article. Therefore, we have provided it as a downloadable JSON file:
example-notification-push.json
That is what the value -> Attributes array looks like:

It starts on line 67 and ends on line 193 while the entire file has 221 lines; the red rectangle on the right of the image shows the position of the Attributes array proportionally to the length of the entire text.
Explanation of keys in a notification
Property name | Type | Description |
---|---|---|
ProductId | Guid |
It is a universally unique identifier (UUID) of the product being notified.
Example 8d654e59-d7b6-4a53-b086-c9de764e506b |
ProductName | String |
It is the name of the product being notified assigned within the Catalogue. The value of ProductName can be lengthy and will not usually fit into a single table cell; the concrete example is provided below the table. |
SubscriptionId | Guid |
It is a universally unique identifier (UUID). The Id is a local identifier for the Subscription instance within the Catalogue, assigned upon Subscription creation.
Example 991c4730-cf6f-432a-9f6c-47be0230ff4 |
SubscriptionEvent | Subscription Event enumeration |
The subscription event to be monitored and for which notification is provided:
For "SubscriptionEvent" = "created" the notifications about newly added products to the EOData Catalogue will be sent. For "SubscriptionEvent" = "modified" the notifications about updated products in the EOData Catalogue will be sent. For "SubscriptionEvent" = "deleted" the notifications about removed products from the EOData Catalogue will be sent. Example created |
NotificationDate | DateTimeOffset |
Date and time at which the notification was generated. Time is in ISO 8601 format (UTC+0): YYYYMM-DDThh:mm:ss.sssZ
Example 2024-01-29T10:59:08.698Z |
value | JSON object | It contains a standard Catalogue API response with all metadata and content details about a product. |
Example of ProductName
S2A_MSIL2A_20240129T062121_N0510_R034_T44VMN_20240129T093752.SAFE
Changing push subscription status and endpoint
In this section you will learn how to edit an existing push subscription. This might be needed if, say, you want to pause or unpause such a subscription, or you know that you will soon lose access to your current notification endpoint.
For push subscriptions, you can edit the following properties:
- Status
Status of the subscription - running, paused or cancelled. Setting status of a subscription to cancelled deletes that subscription.
- NotificationEndpoint
The URL of your endpoint, alongside with the port under which it is available.
- NotificationEpUsername
The username configured on your endpoint used to send notifications to it.
- NotificationEpPassword
The password configured on your endpoint used to send notifications to it.
To perform such an edit, send PATCH HTTP request with a body which is a JSON object containing all parameters which you want to change.
Note
You don’t have to include all parameters; you only need the ones you want to change.
This is the URL to which you should send it. In it, replace <<subscription_id>> with the ID of your subscription.
https://datahub.creodias.eu/odata/v1/Subscriptions(<<subscription_id>>)
REMINDER: Include the obligatory headers.
Response will vary depending on options you chose.
If you:
edit properties such as notification endpoint or status, and
do not set status to cancelled,
you should get response status 200 OK and JSON object containing updated information regarding your subscription.
If you set subscription status to cancelled, your subscription should be removed and you should get response code 204 No Content.
Example: Non-destructive edit
Let’s say that we have a push subscription with ID 6d73b84b-93c6-42aa-8c87-036585cfce04 and we want to change endpoint to which the notifications are being sent. More specifically:
change notification endpoint to https://example.org,
change username used to authenticate to that endpoint to John, as well as
change password used to authenticate to that endpoint to MyTestPassword321,
This is a JSON object which we will include as a body of our HTTP PATCH request to achieve this goal:
{
"NotificationEndpoint": "https://example.org",
"NotificationEpUsername": "John"
"NotificationEpPassword": "MyTestPassword321"
}
REMINDER: Include the obligatory headers.
We send this request to the following URL:
https://datahub.creodias.eu/odata/v1/Subscriptions(6d73b84b-93c6-42aa-8c87-036585cfce04)
We get response code 200 OK, as well as the following JSON object:
{
"Id": "6d73b84b-93c6-42aa-8c87-036585cfce04",
"FilterParam": "Collection/Name eq 'SENTINEL-1' and Attributes/OData.CSC.StringAttribute/any(att:att/Name eq 'productType' and att/OData.CSC.StringAttribute/Value eq 'IW_SLC__1S')",
"StageOrder": false,
"Priority": 1,
"Status": "paused",
"NotificationEndpoint": "https://example.org",
"SubscriptionEvent": [
"created",
"modified"
],
"SubmissionDate": "2025-04-10T12:01:29.231216Z",
"@odata.context": "$metadata#OData.CSC.Subscription"
}
While it does not contain new credentials, we can see new endpoint in it.
Example: Setting subscription status to cancelled
Let’s say that we want to delete subscription from example above by setting its status to cancelled.
For this purpose, we will use the following JSON object as a body of our HTTP PATCH request:
{
"Status": "cancelled"
}
The URL remains the same:
https://datahub.creodias.eu/odata/v1/Subscriptions(6d73b84b-93c6-42aa-8c87-036585cfce04)
We get response code 204 No Content. Our subscription should now be deleted.
Listing current subscriptions
To all list subscriptions currently associated with your account, send GET request to the following URL:
https://datahub.creodias.eu/odata/v1/Subscriptions/Info
REMINDER: Include the obligatory headers.
The status of the response should be 200 OK. You should get a list of your current subscriptions. This includes:
push subscriptions, as well as
pull subscriptions.
Here is an example:
[
{
"Id": "0a449cc9-d6d4-4db7-af6a-d10105bedd2b",
"FilterParam": "Collection/Name eq 'SENTINEL-2' and Attributes/OData.CSC.StringAttribute/any(att:att/Name eq 'productType' and att/OData.CSC.StringAttribute/Value eq 'S2MSI2A')",
"StageOrder": false,
"Priority": 1,
"Status": "paused",
"NotificationEndpoint": "https://example.com/notification",
"SubscriptionEvent": [
"created"
],
"SubmissionDate": "2025-04-10T13:11:11.203179Z",
"@odata.context": "$metadata#OData.CSC.Subscription"
},
{
"Id": "e9d0b04b-cb58-4963-814c-e6d81be4219e",
"FilterParam": "Collection/Name eq 'SENTINEL-1' and Attributes/OData.CSC.StringAttribute/any(att:att/Name eq 'productType' and att/OData.CSC.StringAttribute/Value eq 'IW_SLC__1S')",
"StageOrder": false,
"Priority": 1,
"Status": "running",
"SubscriptionEvent": [
"created",
"modified"
],
"SubmissionDate": "2025-04-10T13:13:51.988546Z",
"@odata.context": "$metadata#OData.CSC.Subscription"
}
]
In this example, we see that the user has two subscriptions:
A push subscription which tracks created products
A pull subscription which tracks both created and modified products
A push subscription, contrary to a pull subscription, includes key NotificationEndpoint which shows URL of endpoint to which the notifications are to be delivered.
You can learn more about pull subscriptions here Push subscriptions to CREODIAS EODATA catalogue
If you don’t currently have any subscriptions, the query should return an empty list:
[]
Example: Listing subscriptions using Python
Here is a complete Python code for listing subscriptions:
import requests
import json
access_token = ""
headers = {
"Content-Type": "application/json",
"Authorization": f"Bearer {access_token}",
}
url = "https://datahub.creodias.eu/odata/v1/Subscriptions/Info"
response = requests.get(url=url, headers=headers)
print(f"{response.status_code} {response.reason}\n")
try:
print(json.dumps(json.loads(response.text), indent=4))
except Exception as e:
print(e)
print(response.text)
This script:
Sends an HTTP request to the specified URL.
Retrieves and displays the results, which consist of:
The response status code (e.g., 200) and reason (e.g., OK).
A blank lane (for readibility).
Response code, if present. (If it is a valid JSON, it will be formatted to make it more legible.)
Assign Keycloak token obtained by following Prerequisite No. 5 to variable access_token.
Save the file as http_request_test_list.py
To run this script, execute the following command (assuming you are in the same folder as the script):
python3 http_request_test_list.py
python http_request_test_list.py
Deleting a subscription
Method 1: Send a DELETE HTTP request
Send a DELETE request to the URL below. In it, replace <<subscription_id>> with the ID of the subscription you want to delete.
https://datahub.creodias.eu/odata/v1/Subscriptions(<<subscription_id>>)
REMINDER: Include the obligatory headers.
You should get response status: 204 No Content.
Listing subscriptions (as explained in section Listing current subscriptions of this article) should show that this subscription no longer exists.
Method 2: Change subscription status to cancelled
This process is described in section Changing push subscription status and endpoint of this article.
What To Do Next
Once you have received a notification, you might want to download that product. The approaches to reaching this objective include:
Copying product from /eodata folder on a virtual machine running on CREODIAS cloud: How to mount eodata using s3fs in Linux on CREODIAS. Value of key S3Path in a notification contains the location of that product within the EODATA repository.
Downloading product as explained in Using curl and wget to download EODATA products from CREODIAS. Value of key ProductId contains the ID of the product which you can use to perform the download as explained in that article.
These articles cover some of the available ways of processing EODATA: