Notifications

last updated: November 10, 2021

The Subscriptions API supports notifications to make it easier for you to monitor your subscriptions. Notifications give you visibility into specific events in a subscription’s lifecycle.

You can keep polling for subscriptions results periodically to determine the status and understand final items delivered. But webhook notifications proactively notify you when a subscription matches and delivers an item so you have confidence that you have all the expected imagery.

Subscription notifications send messages in the form of notification topics. A topic is a specific event type that you can choose to be notified about. The Subscriptions API supports the following topics:

  • delivery.success - an item is delivered.
  • delivery.match - an item match occurred.
  • delivery.failed - an item delivery failed.
  • status.backfill.completed - a backfill completed.
  • status.completed - a subscription completed.
  • status.cancelled - a subscription was cancelled.
  • status.pending - a subscription is pending.
  • status.all - any and all Subscription level changes.
  • status.suspended - a subscription has been suspended.
  • status.failed - a subscription failed.

To enable webhooks for a subscription, include a “notifications” object with a webhook URL and a set of notification topics in the notification. You must specify at least one topic, and a valid webhook URL (a callback where you expect to receive updates) using the scheme https (e.g.: https://host:8654/webhook/path).

Responding to a Webhook

Your client must acknowledge that it received data by sending a 200 OK response. Any response outside of the 200 range, including 3XX HTTP redirection codes, is a failure, indicating that you didn't receive the webhook. Planet doesn't follow redirects for webhook notifications and considers them to be an error response.

Planet attempts “best effort” delivery. Events are sent in order, for each subscription and topic, however, we do not guarantee sequence of event delivery.

In rare circumstances, you might experience delays in receiving webhooks. However, webhooks are always sent with the most recent data for the given subscription. The payload of the delivered webhook should reflect the most recent attributes for the subscription between the time of the webhook's trigger and the webhook's eventual delivery.

If no 200 OK response is received, Planet attempts to deliver the event 3 times with exponential backoff.

The following example creates a subscription that will notify:

  • when a subscription filter match occurs.
  • when that matched item is delivered.
  • when that matched item fails to deliver.
  • when a backfill completes.

POST example

POST: https://api.planet.com/subscriptions/
{
    "name": "Example Subscription",
    "source": {
        "type": "catalog",
        "parameters": {
            "geometry": {
                "coordinates": [[[139.5648193359375,35.42374884923695],
                                [140.1031494140625,35.42374884923695],
                                [140.1031494140625,35.77102915686019],
                                [139.5648193359375,35.77102915686019],
                                [139.5648193359375,35.42374884923695]]],
                "type": "Polygon"
            },
            "start_time": "2021-03-01T00:00:00Z",
            "end_time": "2023-08-31T00:00:00Z",
            "item_types": ["PSScene"],
            "asset_types": ["ortho_analytic_4b"]
        }
    },
    "delivery": {
        "type": "google_cloud_storage",
        "parameters": {
            "bucket": "<my-bucket>",
            "credentials": "<my-credentials>"
        }
    },
    "notifications": {
        "webhook": {
            "url": "https://example.com/post",
            "topics": [
                "delivery.success",
                "delivery.match",
                "delivery.failed",
                "delivery.backfill.completed"
            ]
        }
    }
}

Webhook Event Body

Clients can expect the event body payload to contain the following attributes:

  • schema_version: the schema version of the webhook body.
  • subscription_id: the subscription ID that triggered the event.
  • topic: the event topic.
  • name: the name of the subscription.
  • result: a string or object with the results of the event.
    • For delivery.success, delivery.match, delivery.failed, results will be an object. All other topics will be a string.
  • timestamp: the timestamp of the event.

“delivery.success” topic body example

{
    "schema_version": "0.0.1",
    "subscription_id": "1c7fb0c8-ae1d-45db-8def-fd3a4bffba71",
    "topic": "delivery.success",
    "name": "Example subscription with delivery success notification",
    "result": {
        "delivered": [ "1c7fb0c8-ae1d-45db-8def-fd3a4bffba71/20201128_014059_74_1066/20201128_014059_74_1066_metadata.json",
        "1c7fb0c8-ae1d-45db-8def-fd3a4bffba71/20201128_014059_74_1066/20201128_014059_74_1066_3B_AnalyticMS.tif"
        ]
    },
    "timestamp": "2021-09-21T15:33:40Z"
}

“delivery.match” topic body example

{
    "schema_version": "0.0.1",
    "subscription_id": "1c7fb0c8-ae1d-45db-8def-fd3a4bffba71",
    "topic": "delivery.match",
    "name": "Example subscription with delivery match notification",
    "result": {
        "item_id": "20201128_014059_74_1066"
        },
    "timestamp": "2021-09-21T15:32:49Z"
}