Uber Developers

Courier Update Webhook

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

A webhook of type event.courier_update will be sent every 20 seconds, commencing from the moment a courier is assigned (i.e. when the delivery status transitions to “pickup”). The payload of this webhook includes lat and long to provide your application with the up-to-date location of the courier.

Similar to the delivery_status event, the courier_update event also includes a data object that contains an up-to-date copy of all delivery information.

¶ 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.

{
    "created": "2023-07-06T05:09:07.173Z",
    "data": {
        "batch_id": "bat_ISjTutXjV3GhWp_bRn_iPA",
        "complete": false,
        "courier": {
            "img_href": "https://d1w2poirtb3as9.cloudfront.net/default.jpeg",
            "location": {
                "lat": 40.71093,
                "lng": -74.0119
            },
            "location_description": "",
            "name": "Cori R.",
            "phone_number": "+11111111111",
            "rating": "5.00",
            "vehicle_color": "white",
            "vehicle_make": "Toyota",
            "vehicle_model": "Prius",
            "vehicle_type": "car"
        },
        "courier_imminent": false,
        "created": "2023-07-06T05:06:02.411Z",
        "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",
            "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-07-06T05:56:08Z",
        "dropoff_eta": "2023-07-06T05:20:00.098Z",
        "dropoff_ready": "2023-07-06T05:06:02Z",
        "external_id": "",
        "fee": 9200,
        "id": "del_y_aY8RuTQ0CRKu2aFXe8qQ",
        "kind": "delivery",
        "live_mode": false,
        "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"
        },
        "pickup_action": "default",
        "pickup_deadline": "2023-07-06T05:26:02Z",
        "pickup_eta": "2023-07-06T05:10:27.161Z",
        "pickup_ready": "2023-07-06T05:06:02Z",
        "quote_id": "dqt_y_aY8RuTQ0CRKu2aFXe8qQ",
        "route_id": "rte_THoz2XrARG-JBNW15eRecg",
        "status": "pickup",
        "tracking_url": "https://www.ubereats.com/tw/orders/cbf698f1-1b93-4340-912a-ed9a1577bca9",
        "undeliverable_action": "",
        "undeliverable_reason": "",
        "updated": "2023-07-06T05:08:25.53Z",
        "uuid": "CBF698F11B934340912AED9A1577BCA9"
    },
    "delivery_id": "del_y_aY8RuTQ0CRKu2aFXe8qQ",
    "id": "evt_WNjLziAJT4eiOKgPsLNtbw",
    "kind": "event.courier_update",
    "live_mode": true,
    "location": {
        "lat": 40.71093,
        "lng": -74.0119
    }
}

¶ Fields Definition

Field	Description
`created`	Timestamp indicating when the event was generated.
`delivery_id`	Unique identifier of the delivery the event applies to.
`id`	Unique identifier for this event instance.
`kind`	The kind of event in more detail (event.courier_update).
`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.
`location.lat`	Latitude indicating the courier’s location.
`location.lng`	Longitude indicating the courier’s location.

¶ 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`	Unique 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.
`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] 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`	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.
`complete`	Flag indicating if the delivery is ongoing.
`kind`	The 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 ideintifier 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 `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. Flag 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`	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).