Notifications

When using the ICEYE API Platform, there are several kinds of interaction flows where a client needs to wait for an unspecified length of time for something to happen before proceeding, for example:

  • After creating a task, a client needs to wait for an unknown period of time before it can download tasking products.

  • After ordering STAC items from the public catalog, a client needs to wait before downloading the purchased products.

For better handling of these asynchronous interactions, ICEYE provides the Notifications API. The Notifications API enables you to use webhooks to learn when resources are updated in the ICEYE system. Your client will receive callback notifications from the ICEYE system as soon as the resource status changes.

Notifications flow

To illustrate how the notifications flow works, consider the case of using a webhook to receive notifications when the task status changes — for example, to be notified when a tasked image becomes available for download from the delivery location (task status transitions to FULFILLED or DONE).

Notifications overview

The following components participate in this flow:

  • CLIENT — represents your client application that is integrated with ICEYE API Platform.

  • HTTPS SERVER — represents your HTTPS server that you implemented to receive notification callbacks from ICEYE.

  • TASKING API — represents the ICEYE Tasking API.

  • NOTIFICATIONS — represents the ICEYE Notifications API.

In this tasking example, the client has the following series of interactions with the ICEYE system:

  1. The client invokes the registerWebhook operation on the Notifications API to create a new webhook (must be done only once).

    The payload of the registerWebhook request contains the URL of the callback HTTPS server and the response message contains the webhook ID of the newly created webhook.

  2. The client invokes the createTask operation, including the webhook ID in the request. By including the webhook ID, the client signals that it intends to use the notifications flow for this task.

  3. Whenever the the status of the created task changes, ICEYE API Platform posts a callback message containing the task ID of the updated task to your callback HTTPS server.

  4. The callback HTTPS server processes the callback message and generates an internal event to the client, signalling that the task status has changed.

  5. The client invokes the getTask operation to retrieve the current task status.

  6. If the task status is FULFILLED or DONE, the client can retrieve the tasking products by invoking the getTaskProducts operation.

Implementing a callback HTTPS server

In order to receive callbacks from the ICEYE notification service, you must implement a callback HTTPS server. The HTTPS server parses the callback messages from the notification service and generates corresponding internal events to trigger actions in your client.

For example, if the HTTPS server receives a callback of type tasking, it could generate an internal event to signal that the client should check the corresponding task status.

Security requirements

We recommend that you implement the callback HTTPS server with the following security features:

  • Protect the HTTP endpoint with SSL/TLS security — in order to encrypt the content of callback messages and to prevent man-in-the-middle attacks, enable SSL/TLS security on the HTTP server endpoint.

  • X.509 certificate — when configuring SSL/TLS security, configure it with an X.509 certificate satisfying the following conditions:

    • The certificate is signed by a well-known certificate authority.

    • The certificate’s subject name (defined either by the subjectAltName extension or by the subject’s common name) must match the hostname where the HTTPS server is deployed (RFC-3280).

  • HTTP Basic Authentication — you can optionally enable HTTP Basic Authentication on your HTTPS server, in which case you must be prepared to parse the login credentials from the Authorization header. A typical HTTP Authorization header has the following format:

    Authorization: Basic XXXXXXXXXXXXXXXXXX

    The credentials string following the Basic keyword is generated by combining the username and password with a colon (username:password) and then base64 encoding this string (RFC-7617).

  • Client Credentials Authentication — you can optionally enable OAuth2 Client Credentials authentication on your HTTPS server, in which case you must be prepared to parse a Bearer token from the Authorization header. A typical HTTP Authorization header with Bearer token has the following format:

    Authorization: Bearer XXXXXXXXXXXXXXXXXX

    The token passed in this header is an OAuth2 access token issued by your Identity provider’s Token endpoint (the ICEYE system invokes the Token endpoint to obtain the access token prior to sending the callback notification). Generally, your security provider should provide a client library or API for verifying the access token.

Processing the callback payload

The HTTPS server must be prepared to process the callback payload received from the notification service. The notification service sends the callback payload by invoking HTTP POST on the HTTPS server, with the following JSON data in the message body:

{
    "resourceID": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    "resourceKey": "tasking",
    "data": {
        ...
    }
}

The payload data object contains the following properties:

Property Description

resourceKey

Type of resource that was updated (for example tasking).

resourceID

Unique identifier for the resource that was updated (for example, task ID or delivery ID).

data

(Optional) Additional metadata, which is provided for certain kinds of notification events. See Payloads for data delivery.

The following resource types are supported:

resourceKey Value in resourceID Description

tasking

task ID

Callback signals that the status of the task with the given task ID was recently updated.

catalog_purchase

purchase ID

Callback signals that the status of the Catalog purchase with the given purchase ID was recently updated.

Payloads for data delivery

In the case of successful delivery of tasked imaging products or catalog products, the callback payload includes the following metadata in the data object:

Property Description

deliveryTime

Timestamp of delivery (specified in RFC 3339 date-time format).

locations

An array of delivery location objects, specifying the locations where products have been delivered. See Delivery locations.

files

An array of file objects, providing the locations of metadata files (not included, if the products are delivered in a bundled Zip file). File objects are provided only for metadata files, not product files.

checksum

If products are delivered in a bundled Zip file, this property provides the checksum of the Zip file in SHA256 format.

The file objects have the following format:

Property Description

type

Type of file (metadata).

name

File name of the delivered file (not including the file path).

path

Path to a group of files. The full path to the file location is given by the combination path/subpath.

subpath

Subpath to the file location. The full path to the file location is given by the combination path/subpath.

In the case of failed delivery of tasked imaging products or catalog products, the callback payload includes the following metadata in the data object:

Property Description

status

A string that indicates the status of the failed delivery.

HTTP response

To indicate that the callback was successfully processed, the HTTPS server should return one of the following responses:

  • HTTP 200

  • HTTP 201

The ICEYE notification service requires the HTTP 20x response, in order to confirm that the notification was successful.

In future, the notification service will retry the notification, if it receives an error response.