Notifications

While you can poll the Orders API for an order periodically to determine its state and whether it is ready for download, the Orders API also supports email and webhook notification options, making it easier for you to follow order progress.

Email Notifications

To enable email notifications for an order, you can specify "email": true as a notification option in your order request. By default, this value will be set to false. When enabled, an email will be delivered to the email address of the user who created the order when the order reaches a success, partial, or failed state.

JSON

"notifications": {
    "email": true
}

Python SDK

from planet.order_request import notifications

notification = notifications(email=True)

Webhook Notifications

To enable webhook notifications for an order, you can specify a webhook URL for notification when your order is ready. If a cloud storage delivery option is not specified in the order, the webhook will contain the URLs to the downloadable files.

By default, the provided webhook will be called for each delivered item. You can request a single webhook call per order by including the "per_order": true parameter.

If desired, HTTP basic authentication is supported and credentials can be specified in the webhook URL. For example: https://user:pass@example.com/post.

JSON

"notifications": {
    "webhook": {
        "per_order": true,
        "url": "https://example.com/post"
    }
}

Python SDK

from planet.order_request import notifications

notification = notifications(
    webhook_per_order=True, webhook_url="https://example.com/post"
)

Example Webhook Payloads

Cloud delivery

{
  "items": [
    {
      "name": "{file-name}",
      "delivery": "success",
      "expires_at": "0001-01-01T00:00:00.000Z"
    }
  ],
  "order_id": "{order-id}"
}

Download links

{
  "items": [
    {
      "name": "{file-name}",
      "delivery": "success",
      "location": "?token={download-token}",
      "expires_at": "2025-01-01T12:00:00.000Z"
    }
  ],
  "order_id": "{order-id}"
}