Notifications

When using the ICEYE Constellation API Suite (ICAS), 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 is updated.

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

  • 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 status of the created task changes or whenever the task’s scene changes (for example, when the task’s imaging time is updated), ICAS 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 was updated.

  5. The client invokes the getTask and getTaskScene operations to retrieve the task resource and check the update(s).

  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 task with the given task ID was recently updated. This includes status transitions (e.g. ACTIVE → FULFILLED) as well as changes to the task’s scene.

purchase

catalog purchase ID

Callback signals that a catalog purchase with the given purchase ID reached a terminal state. The callback is sent only when the purchase is closed or failed, and the data object carries the terminal status and the purchased itemIDs.

delivery

delivery ID

Callback signals that the status of the delivery request with the given delivery ID was recently updated (for example, PENDING → SUCCESS or PENDING → FAILED).

The sections under Event payloads describe each event type in detail, including when it is triggered, the shape of the data object, and the recommended follow-up action.

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.

Event payloads

The following sections describe, for each supported resourceKey, when the callback is triggered, the shape of the data object, and the recommended follow-up action.

tasking event

This callback is triggered when:

  • The status of the task changes (for example, ACTIVE → FULFILLED, ACTIVE → EXPIRED).

  • The task’s scene changes (for example, the imaging time is updated or the acquisition ID changes).

The data object is empty — the callback is a signal that something about the task was updated. Use the resourceID to fetch the latest task state from the Tasking API.

Example payload
{
    "resourceID": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "resourceKey": "tasking",
    "data": {}
}
Recommended action — call getTask and getTaskScene with the resourceID to retrieve the updated task details and scene.
purchase event

This callback is triggered when a catalog purchase reaches a terminal state:

  • All processing jobs for the purchase complete and it transitions to closed.

  • The purchase transitions to failed.

The purchase callback carries metadata about the terminal outcome in the data object:

Property Description

status

The terminal status of the purchase — either closed or failed.

itemIDs

An array of the STAC item UUIDs associated with the purchased acquisitions. Use these UUIDs with the Catalog API to retrieve item metadata and download the delivered products.
Example payload — closed purchase
{
    "resourceID": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "resourceKey": "purchase",
    "data": {
        "status": "closed",
        "itemIDs": ["7f2c9b4a-1d3e-4a2b-9c8f-0a1b2c3d4e5f", "9a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d"]
    }
}
Example payload — failed purchase
{
    "resourceID": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "resourceKey": "purchase",
    "data": {
        "status": "failed",
        "itemIDs": ["7f2c9b4a-1d3e-4a2b-9c8f-0a1b2c3d4e5f"]
    }
}
Recommended action — call getPurchase with the resourceID to retrieve the updated purchase status and, once the purchase is closed, list the purchased products with listPurchaseProducts.
delivery event

This callback is triggered when:

  • The status of a delivery request changes (for example, PENDING → SUCCESS or PENDING → FAILED).

Like the PURCHASE event and unlike tasking, the delivery callback carries metadata about the delivery outcome in the data object. See Payloads for data delivery for the full property reference, including the schema of the locations and files objects.

Example payload — successful delivery
{
    "resourceID": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "resourceKey": "delivery",
    "data": {
        "deliveryTime": "2025-06-15T10:30:00Z",
        "locations": [
            {
                "configID": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                "path": "DOC-EXAMPLE-BUCKET",
                "subpath": "folder1/"
            }
        ],
        "files": [
            {
                "type": "metadata",
                "name": "metadata.json",
                "path": "DOC-EXAMPLE-BUCKET",
                "subpath": "folder1/"
            }
        ],
        "checksum": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
    }
}
Example payload — failed delivery
{
    "resourceID": "d290f1ee-6c54-4b01-90e6-d701748f0851",
    "resourceKey": "delivery",
    "data": {
        "status": "FAILED"
    }
}
Recommended action — for successful deliveries, use the locations and files information to access the delivered products. For failed deliveries, call getDelivery to inspect the delivery status and decide whether to retry.

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.