Webhooks

Webhooks provide an active feedback mechanism so that you can keep track of your delivery orders in near real time without making a request.

Webhook payloads will include important details about the event. For example, if enabled this is where parking bay information will be sent in ARRIVED_AT_PICKUP and ARRIVED_AT_RETURN events.

Simply provide Dolly with a URL where you host a webhook receiver and we will notify your listener whenever an event occurs. You may need to whitelist our IPs so that our webhook calls can make it to your receiver. Status updates are also provided via the Get Delivery Info endpoint.

The following section names and describes the events we fire webhooks for:

Event NameEvent Description
COURIER_REQUESTEDDolly has received and successfully processed the order.
CONFIRMEDA helper has been assigned to your delivery.
EN_ROUTE_TO_PICKUPHelper is on the way to pickup a delivery at the pickup location
ARRIVED_AT_PICKUPHelper has arrived at the pickup location
PICKED_UPHelper has picked up the delivery from the pickup location
EN_ROUTE_TO_DROPOFFHelper is on the way to drop off the delivery at the destination
ARRIVED_AT_DROPOFFHelper has arrived at the delivery destination
EN_ROUTE_TO_RETURNHelper is on the way to return the order to the pickup location
ARRIVED_AT_RETURNHelper has arrived at the pickup location to return the order
DELIVEREDHelper has completed the delivery
RETURNEDThe order has been returned
CANCELLEDThe delivery has been cancelled

When a delivery is canceled there will be an associated cancel reason. Currently the only available cancel reason is OTHER, while adding more reason codes is on the upcoming roadmap.

We also support including a cancel comment as a string.

Cancel ReasonCancel Reason Description
OTHERThe delivery was canceled.

A webhook event will contain a payload of data reflecting the delivery it pertains to. The payload will have some or all of the following schema:

 {
    id: 'string',
    actualDeliveryTime: 'string',
    actualOrderTime: 'string',
    actualPickupTime: 'string',
    actualReturnTime: 'string',
    batchId: 'string',
    cancelledBy: 'string',
    cancelReasonCode: 'string',
    clientId: 'string',
    containsAlcohol: 'boolean',
    courier: {
      email: 'string',
      firstName: 'string',
      fullName: 'string',
      id: 'string',
      lastName: 'string',
      location: {
        latitude: 'number',
        longitude: 'number',
      },
      maskedPhoneNumber: 'string',
      phoneNumber: 'string',
      vehicle: {
          color: 'string',
          licensePlate: 'string',
          make: 'string',
          model: 'string',
        },
      } ,
    currency: 'string',
    deliveryWindowEndTime: 'string', // date format
    deliveryWindowStartTime: 'string', // date format
    drivingDistance: 'number',
    dropoffEta: 'number',
    dropoffInfo: {
      dropoffAddress: {
        addressLine1: 'string',
        addressLine2: 'string',
        city: 'string',
        country: 'string',
        neighborhood: 'string',
        state: 'string',
        zipCode: 'string',
      },
      dropoffContact: {
        firstName: 'string',
        fullName: 'string',
        lastName: 'string',
        phone: 'string',
      },
      dropoffInstruction: 'string',
      dropoffLocation: {
        latitude: 'number',
        longitude: 'number',
      },
      isUnattended: 'boolean',
      neighborhood: 'string',
      signatureRequired: 'boolean',
    },
    dropoffVerification: {
        barcodeInfo: [
          {
            barcode: { type: 'string' },
            scanStatus: { type: 'string' },
          }
        ],
        deliveryProofImageUrl: 'string',
        signatureImageUrl: 'string',
    },
    estimatedDeliveryTime: 'string', // date format
    estimatedPickupTime: 'string', // date format
    estimatedReturnTime: 'string', // date format
    externalDeliveryId: 'string',
    externalOrderId: 'string',
    externalStoreId: 'string',
    externalStoreName: 'string',
    fee: 'number',
    isAutonomousDelivery: 'boolean',
    marketName: 'string',
    orderInfo: { $ref: 'OrderInfo' },
    partnerId: 'string',
    pickupEta: 'number',
    pickupInfo:  {
        parkingBayEnabled: 'boolean',
        pickupAddress: {
          addressLine1: 'string',
          addressLine2: 'string',
          city: 'string',
          country: 'string',
          neighborhood: 'string',
          state: 'string',
          zipCode: 'string',
        },
        pickupContact: {
          firstName: 'string',
          fullName: 'string',
          lastName: 'string',
          phone: 'string',
        },
        pickupInstruction: 'string',
        pickupLocation: {
          latitude: 'number',
          longitude: 'number',
        },
        signatureRequired: 'boolean',
			},
    pickupParkingSlot: 'string',
    pickupVerification: {
        barcodeInfo: [
          {
            barcode: { type: 'string' },
            scanStatus: { type: 'string' },
          }
        ],
        deliveryProofImageUrl: 'string',
        signatureImageUrl: 'string',
      },
    pickupWindowEndTime: 'string', // date format
    pickupWindowStartTime: 'string',
    returnEta: 'number',
    returnParkingSlot: 'string',
    returnReasonCode: 'string',
    status: 'string',
    statusWhenCancelled: 'string',
    storeName: 'string',
    submitPlatform: 'string',
    test: 'boolean',
    timestamp: 'string',
    tip: 'number',
    tipAddedTime: 'string',
    tipStatus: 'string',
}

Source IP Addresses

If your webhook destination requires IP whitelisting to allow connections, the following Dolly IP addresses should be added to your whitelist:

  • 44.238.152.36
  • 44.232.216.253
  • 52.41.182.222