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.
Example Request
POST https://api.planet.com/compute/ops/orders/v2
{
"name":"simple order",
"source_type": "scenes",
"products":[
{
"item_ids":[
"20220304_093300_37_2430",
"20220304_093257_90_2430",
"20220304_103324_1105",
"20220304_103325_1105"
],
"item_type":"PSScene",
"product_bundle":"analytic_udm2"
}
],
"notifications":{
"email": true
}
}
Webhook Notifications¶
To enable webhook notifications for an order, you can specify 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.
Example Request
POST https://api.planet.com/compute/ops/orders/v2
{
"name":"simple order",
"source_type": "scenes",
"products":[
{
"item_ids":[
"20220304_093300_37_2430",
"20220304_093257_90_2430",
"20220304_103324_1105",
"20220304_103325_1105"
],
"item_type":"PSScene",
"product_bundle":"analytic_udm2"
}
],
"notifications":{
"webhook":{
"per_order": true,
"url":"{URL}"
}
}
}
Example Webhook Body
{
"_links": {
"_self": "https://api.planet.com/compute/ops/orders/v2/02fb0492-006f-44ad-8370-7b59a935f076"
},
"created_on": "2022-11-16T03:46:59.559Z",
"error_hints": [],
"id": "02fb0492-006f-44ad-8370-7b59a935f076",
"last_message": "Preparing order",
"last_modified": "2022-11-16T03:46:59.559Z",
"name": "simple order",
"notifications": {
"webhook": {
"per_order": true,
"url": "<REDACTED>"
}
},
"products": [
{
"item_ids": [
"20220304_093300_37_2430",
"20220304_093257_90_2430",
"20220304_103324_1105",
"20220304_103325_1105"
],
"item_type": "PSScene",
"product_bundle": "analytic_udm2"
}
],
"source_type": "scenes",
"state": "queued"
}
We are continually working to improve our technical documentation and support. Please help by sharing your experience with us.