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
- Python SDK
"notifications": {
"email": true
}
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
- Python SDK
"notifications": {
"webhook": {
"per_order": true,
"url": "https://example.com/post"
}
}
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}"
}