Uber Developers

Delivery Status Webhook

WEBHOOK: POSThttps://<YOUR_WEBHOOK_URI> event_type: event.delivery_status

A Webhook of type event.delivery_status will be sent whenever the delivery status or courier_imminent changes.

The delivery status Webhook event will contain a status field to give you the new status, and a data field that gives you up-to-date delivery data. For examples, please check the sample webhook.

¶ Definition of Delivery Status

This table illustrates the status and courier_imminent fields of the webhooks you will receive throughout the delivery lifecycle (note that canceled and returned are not mandatory for every delivery).

#	status	courier_imminent	Action	How is it triggered?
0	pending	–	Delivery has been accepted but does not yet have a courier assigned	Via API once the delivery is created
1	pickup	FALSE	Courier is assigned and moving towards the pickup	Via the courier App (manually) after the courier accepted the delivery offer card
2	pickup	TRUE	Courier is 1 minute away from the pickup	Via the courier App (automatically) after GPS detects the courier is 1 minute away from the pickup location
3	pickup_complete	–	Courier completed the pickup	Via the courier App (manually) after the courier swiped to complete the pickup
4	dropoff	FALSE	Courier is moving towards the dropoff	Via the courier App (manually) after the courier swiped to complete the pickup
5	dropoff	TRUE	Courier is 1 minute away from the dropoff	Via the courier App (automatically) after GPS detects the courier is 1 minute away from the dropoff location
6	delivered	—	Courier has completed the delivery	Via the courier App (manually) after the courier swiped to complete the dropoff
–	canceled	–	Delivery has been canceled	This could either be due to the use of CancelDelivery endpoint, canceled via the Direct Dashboard or an internal reason
–	returned	–	Delivery has been canceled and the undeliverable_action is return (default action)	The delivery was canceled and a new delivery was created to return items to the sender. (See related_deliveries in the delivery object.)

IMPORTANT Please note that if a trip is returned, we will automatically create a new delivery for the return trip and it will be included in the webhook response under the return object. The original delivery will have an ID starting with del_, while the returned delivery will have an ID starting with ret_. The status relationship between these two deliveries is illustrated as follows:

#	Original Delivery Status (del_)	Return Job Status (ret_)
1	pending
2	pickup
3	pickup_complete
4	dropoff
5	canceled	pickup
6		pickup_complete
7		dropoff
8	returned	delivered

¶ Sample Webhook

The fields may vary based on different statuses and situations. For accurate field definitions, please refer to the Fields Definition and verify them on your own.

NOTE: We don’t include courier lat/long and vehicle information in the “delivered” webhook, as shown in this example. This information is only displayed in previous webhook statuses.

{
    "account_id": "",
    "batch_id": "bat_voEiX66nUf-D4XzKRlpJLQ",
    "created": "2023-08-01T06:28:22.695Z",
    "customer_id": "fb109f30-d2f0-5447-a0fa-884a44394axx",
    "data": {
        "batch_id": "bat_voEiX66nUf-D4XzKRlpJLQ",
        "complete": true,
        "courier": {
            "img_href": "https://d1w2poirtb3as9.cloudfront.net/default.jpeg",
            "location": {
                "lat": 0,
                "lng": 0
            },
            "name": "Sam",
            "phone_number": "+15555555557",
            "name": "Cori R.",
            "rating": "5.00",
            "vehicle_color": "",
            "vehicle_make": "",
            "vehicle_model": "",
            "vehicle_type": "car"
        },
        "courier_imminent": false,
        "created": "2023-08-01T06:26:13.896Z",
        "currency": "usd",
        "deliverable_action": "deliverable_action_meet_at_door",
        "dropoff": {
            "address": "231 Hudson St, New York, NY 10013",
            "detailed_address": {
                "street_address_1": "231 Hudson St",
                "street_address_2": "",
                "city": "New York",
                "state": "NY",
                "zip_code": "10013",
                "country": "US"
            },
            "location": {
                "lat": 40.724533,
                "lng": -74.00839
            },
            "name": "DROPOFF T.",
            "notes": "",
            "phone_number": "+15555555556",
            "status": "completed",
            "status_timestamp": "2023-08-01T06:28:22.564Z",
            "verification": {
                "barcodes": [
                    {
                        "scan_result": {
                            "outcome": "SUCCESS",
                            "timestamp": "2023-07-06T06:49:05.154Z"
                        },
                        "type": "CODE39",
                        "value": "123"
                    }
                ],
                "picture": {
                    "image_url": "https://tb-static.uber.com/prod/file-upload/uploads/direct-image-capture/bb530825-891d-482a-8f05-6288235d7120"
                },
                "pin_code": {
                    "entered": "9999"
                },
                "signature": {
                    "image_url": "https://tb-static.uber.com/prod/file-upload/uploads/courier-task-platform/signatures/3e030abc-87d7-4f8d-a458-e0f27b489f0b",
                    "signer_name": "Sam",
                    "signer_relationship": "self"
                }
            },
            "verification_requirements": {
                "barcodes": [
                    {
                        "type": "CODE39",
                        "value": "123"
                    }
                ],
                "picture": true,
                "pincode": {
                    "enabled": true,
                    "value": "9999"
                },
                "signature": true,
                "signatureRequirement": {
                    "collect_signer_name": true,
                    "collect_signer_relationship": true,
                    "enabled": true
                }
            }
        },
        "dropoff_deadline": "2023-08-01T07:21:24Z",
        "dropoff_eta": "2023-08-01T06:28:22.564Z",
        "dropoff_ready": "2023-08-01T06:26:14Z",
        "external_id": "",
        "fee": 9200,
        "id": "del_QbLowiwHQM-b4e8YmOZNOw",
        "kind": "delivery",
        "live_mode": true,
        "manifest": {
            "description": "1 X Small Box\n",
            "total_value": 0
        },
        "manifest_items": [
            {
                "dimensions": {
                    "depth": 40,
                    "height": 40,
                    "length": 40
                },
                "must_be_upright": false,
                "name": "Small Box",
                "price": 0,
                "quantity": 1,
                "size": "large"
            }
        ],
        "pickup": {
            "address": "175 Greenwich St, New York, NY 10007",
            "detailed_address": {
                "street_address_1": "175 Greenwich St",
                "street_address_2": "",
                "city": "New York",
                "state": "NY",
                "zip_code": "10007-2438",
                "country": "US"
            },
            "location": {
                "lat": 40.71093,
                "lng": -74.0119
            },
            "name": "Coffee Shop",
            "notes": "",
            "phone_number": "+15555555555",
            "status": "completed",
            "status_timestamp": "2023-08-01T06:27:04.748Z"
        },
        "pickup_action": "default",
        "pickup_deadline": "2023-08-01T06:46:14Z",
        "pickup_eta": "2023-08-01T06:27:04.748Z",
        "pickup_ready": "2023-08-01T06:26:14Z",
        "quote_id": "dqt_QbLowiwHQM-b4e8YmOZNOw",
        "route_id": "rte_I8-ffNPuT82EP1yaBmG1jg",
        "status": "delivered",
        "tracking_url": "https://www.ubereats.com/tw/orders/41b2e8c2-2c07-40cf-9be1-ef1898e64d3b",
        "undeliverable_action": "",
        "undeliverable_reason": "",
        "updated": "2023-08-01T06:28:22.611Z",
        "uuid": "41B2E8C22C0740CF9BE1EF1898E64D3B"
    },
    "delivery_id": "del_QbLowiwHQM-b4e8YmOZNOw",
    "developer_id": "",
    "id": "evt_Bouz7BhPTYGDz9FFQNgODw",
    "kind": "event.delivery_status",
    "live_mode": true,
    "route_id": "rte_I8-ffNPuT82EP1yaBmG1jg",
    "status": "delivered"
}

¶ Fields Definition

Field	Description
`account_id`	Unique identifier (prefixed `acc_`) for the account of the above developer that this delivery belongs to.
`created`	Timestamp indicating when the event was generated.
`customer_id`	Unique identifier (prefixed `cus_`) for the customer this delivery belongs to.
`delivery_id`	Unique identifier of the delivery the event applies to.
`developer_id`	Unique identifier (prefixed `dev_`) for the developer the above customer_id maps to.
`id`	Unique identifier for this event instance.
`kind`	The kind of event in more detail (e.g., event.delivery_status).
`data`	The webhook details. Please refer the Data Object Definition for more information.
`live_mode`	Flag indicating if the event applies to a live vs a test delivery.
`status`	Status of the delivery the event refers to.
`batch_id`	When a delivery is batched, this unique identifier (prefixed `bat_`) indicating the batch that this delivery belongs to. Can be used to identify deliveries batched with the same courier. IMPORTANT: If a courier cancels the delivery while en route to pick up, we will assign the delivery to another courier; therefore, the `batch_id` will change.
`route_id`	Unique identifier (prefixed `rte_`) of the route a courier is taking.

¶ Data Object Definition

The data object contains more detailed information about the webhook.

Field	Description
`id`	Unique identifier of the delivery the event applies to.
`status`	Status of the delivery the event refers to.
`created`	Date/Time at which the delivery was created.
`updated`	Date/Time at which the delivery was last updated.
`pickup_eta`	Estimated time the courier will arrive at the pickup location.
`pickup_ready`	When a delivery is ready to be picked up. This is the start of the pickup window.
`pickup_deadline`	When a delivery must be picked up by. This is the end of the pickup window.
`dropoff_eta`	Estimated time the courier will arrive at the dropoff location.
`dropoff_ready`	When a delivery is ready to be dropped off. This is the start of the dropoff window.
`dropoff_deadline`	When a delivery must be dropped off. This is the end of the dropoff window.
`quote_id`	Identifier for the Delivery quote if one was provided when creating this Delivery.
`fee`	Amount in cents ( ¹/₁₀₀ of currency unit ) that will be charged if this delivery is created. i.e.: $10.99 => 1099.
`currency`	Three-letter ISO currency code, in lowercase.
`deliverable_action`	Specify the action for the courier to take on a delivery. For more detailed information on `deliverable_action`, please refer to the Get Delivery response.
`tip`	Amount in cents ( ¹/₁₀₀ of currency unit ) that will be paid to the courier as a tip.
`manifest.reference`	Reference that identifies the manifest.
`manifest.description`	[DEPRECATED] A detailed description of what the courier will be delivering. It is better to consume the description of each item in `ManifestItem.name`.
`manifest.total_value`	Value in cents ( ¹/₁₀₀ of currency unit ) of the items in the delivery. i.e.: $10.99 => 1099.
`manifest_items.name`	Description of item.
`manifest_items.quantity`	Quantity of items.
`manifest_items.size`	Approximate size of item. Options are small, medium, large, or xlarge. If nothing is specified, small will be applied by default.
`manifest_items.dimensions.length`	Length in centimeters.
`manifest_items.dimensions.height`	Height in centimeters.
`manifest_items.dimensions.depth`	Depth in centimeters.
`manifest_items.price`	Price in cents ( ¹/₁₀₀ of currency unit ). i.e.: $10.99 => 1099.
`manifest_items.weight`	Weight in grams. Note: When using dimensions the weight field is required.
`pickup`	Pickup details for the delivery. Please refer to Delivery Info Definition Table for more details.
`dropoff`	Dropoff details for the delivery. Please refer to Delivery Info Definition Table for more details.
`return`	Return details for the delivery. Please refer to Delivery Info Definition Table for more details.
`courier.name`	Courier’s first name and last name’s initial.
`courier.rating`	[DEPRECATED] Courier’s rating on a scale of 1.0 to 5.0.
`courier.vehicle_type`	Type of vehicle the courier is using. Currently we support bicycle, car, van, truck, scooter, motorcycle, and walker.
`courier.phone_number`	The courier’s phone number.
`courier.location.lat`	Latitude indicating courier’s location.
`courier.location.lng`	Longitude indicating courier’s location.
`courier.img_href`	URL to courier’s profile image.
`live_mode`	Flag indicating if the delivery is in live mode or test mode.
`related_deliveries.id`	Related deliveries is a collection describing other jobs that share an association. Unique identifier for the delivery.
`related_deliveries.relationship`	Flag indicating the nature of the delivery identified in related_deliveries. “original” for the forward leg of the trip, and “returned” for the return leg of the trip.
`tracking_url`	URL to track the courier during the delivery.
`courier_imminent`	Flag that is set to true when the courier is 1 minute away from the pickup or dropoff location.
`undeliverable_reason`	If a delivery was undeliverable, this field will contain the reason why it was undeliverable.
`undeliverable_action`	If a delivery was undeliverable, this field will contain the resulting action taken by the courier. For more detailed information on `undeliverable_action`, please refer to the Get Delivery response.
`complete`	Flag indicating if the delivery is ongoing.
`kind`	Type of object being described (e.g., delivery).
`uuid`	Alternative delivery identifier. “Id” field should be used for any identification purposes. “uuid” field is equally unique but loses contextual information (i.e. nothing in this identifier points out that it relates to a delivery). Unlike “Id” field, “uuid” is case-insensitive. Value for “uuid” field is UUID v4 with ‘-’ characters removed, e.g., 41B2E8C22C0740CF9BE1EF1898E64D3B.
`batch_id`	When a delivery is batched, this unique identifier (prefixed `bat_`) indicating the batch that this delivery belongs to. Can be used to identify deliveries batched with the same courier. IMPORTANT: If a courier cancels the delivery while en route to pick up, we will assign the delivery to another courier; therefore, the `batch_id` will change.
`route_id`	Unique identifier (prefixed `rte_`) of the route a courier is taking.
`cancelation_reason.primary_reason`	Value will always be `#Uber`.
`cancelation_reason.secondary_reason`	Value can be either `CUSTOMER_CANCEL`, `COURIER_CANCEL`, `MERCHANT_CANCEL`, or `UBER_CANCEL`.
`pickup_action`	Specify the action that should be taken at the pickup.

¶ Delivery Info Definition

This table applies to pickup, return and dropoff fields in the Data Object.

Field	Description
`name`	Name of the person at the waypoint.
`phone_number`	Phone number of the waypoint.
`address`	Address of the waypoint.
`detailed_address.street_address_1`	First line of street address of the waypoint.
`detailed_address.street_address_2`	Optional second line of street address of the waypoint.
`detailed_address.city`	City of the waypoint.
`detailed_address.state`	State of the waypoint.
`detailed_address.zip_code`	Zip code of the waypoint.
`detailed_address.country`	Country of the waypoint.
`location.lat`	Latitude for the waypoint location.
`location.lng`	Longtitude for the waypoint location.
`notes`	Additional instructions at the waypoint location.
`verification.signature.image_url`	URL of the signature image done on the waypoint.
`verification.signature.signer_name`	Name of the person who signed for the package.
`verification.signature.signer_relationship`	Relationship of the person who signed for the package to the intended person.
`verification.barcodes.value`	String value encoded in the barcode.
`verification.barcodes.type`	Type of barcode. Valid values: `CODE39`, `CODE39_FULL_ASCII`, `CODE128`, `QR`.
`verification.barcodes.scan_result.outcome`	A string indicating whether the scan is successful or failed.
`verification.barcodes.scan_result.timestamp`	Timestamp indicating when the event was generated.
`verification.picture.image_url`	URL of the image taken at waypoint.
`verification.identification.min_age_verified`	Identification information or scanning information captured. Indicating if ID was successfully verified/scanned.
`verification.pin_code.entered`	Values entered during pin verification.
`verification.completion_location.lat`	Latitude where the job completes.
`verification.completion_location.lng`	Longitude where the job completes.
`verification_requirements.signature`	Flag indicating if signature is required or not at waypoint.
`verification_requirements.signatureRequirement.collect_signer_name`	Flag indicating if the signer’s name is required or not at the waypoint.
`verification_requirements.signatureRequirement.collect_signer_relationship`	Flag indicating if the relationship between sender and the signer is required or not at the waypoint.
`verification_requirements.signatureRequirement.enabled`	Flag indicating if signature is required or not at waypoint.
`verification_requirements.barcodes.type`	String value encoded in the barcode.
`verification_requirements.barcodes.value`	Type of barcode. Valid values: `CODE39`, `CODE39_FULL_ASCII`, `CODE128`, `QR`.
`verification_requirements.picture`	Flag indicating if photo is required or not at waypoint.
`verification_requirements.pincode.enabled`	Flag indicating pincode is required or not at waypoint.
`verification_requirements.pincode.value`	Values entered during pin verification.
`courier_notes`	When a picture is requested as proof-of-delivery, this field contains the notes provided by the courier (e.g., where the items were left).