# Webhook Reference

## Example of delivery callback payload

> This endpoint describes the structure of the payload sent to your configured webhook when a delivery status update occurs. It is not an actual callback trigger.\
> The format of the data is defined in the  \[CallbackDeliveryPayload]\(#components-schemas-CallbackDeliveryPayload) schema.\
> Your webhook must be capable of accepting POST requests with this structure.<br>

```json
{"openapi":"3.0.0","info":{"title":"Swoove","version":"1.0.0"},"servers":[{"description":"Sandbox","url":"https://test.swooveapi.com"},{"description":"Production","url":"https://live.swooveapi.com"}],"paths":{"/webhook/callback-example":{"post":{"tags":["Webhook Reference"],"summary":"Example of delivery callback payload","description":"This endpoint describes the structure of the payload sent to your configured webhook when a delivery status update occurs. It is not an actual callback trigger.\nThe format of the data is defined in the  [CallbackDeliveryPayload](#components-schemas-CallbackDeliveryPayload) schema.\nYour webhook must be capable of accepting POST requests with this structure.\n","responses":{"200":{"description":"Example payload structure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CallbackDeliveryPayload"}}}}}}}},"components":{"schemas":{"CallbackDeliveryPayload":{"type":"object","description":"Payload sent to user's callback URL when delivery status changes","properties":{"success":{"type":"boolean"},"code":{"type":"integer"},"message":{"type":"string"},"responses":{"type":"array","minItems":1,"items":{"type":"object","properties":{"pickup":{"$ref":"#/components/schemas/Location"},"dropoff":{"$ref":"#/components/schemas/Location"},"return_contact":{"type":"object","properties":{"coordinates":{"type":"array","items":{"type":"number"}}}},"full_price":{"$ref":"#/components/schemas/Price"},"contact":{"$ref":"#/components/schemas/Contact"},"return_delivery":{"type":"boolean"},"return_reason":{"type":"string","nullable":true},"distance":{"type":"number"},"individual_pricing_id":{"type":"string"},"status":{"type":"string","enum":["PENDING","CANCELLED","GROUPED","AGENCY_ASSIGNED","ASSIGNED","ONHOLD","PICKUP","PICKEDUP","DROPOFF","DROPEDOFF","ENDED","DELIVERY_PAID_FOR"]},"instructions":{"type":"string"},"reference":{"type":"string"},"start_time":{"type":"number"},"end_time":{"type":"number"},"time_completed":{"type":"number","nullable":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/Item"}},"tracking_code":{"type":"string"},"delivery_code":{"type":"string"},"secret_code":{"type":"string"},"createdAt":{"type":"string"},"updatedAt":{"type":"string"},"tracking_link":{"type":"string"},"proof_of_delivery":{"type":"object","description":"Included only when status is `ENDED`","properties":{"location":{"type":"object","properties":{"latitude":{"type":"number"},"longitude":{"type":"number"},"address":{"type":"string"}}},"_id":{"type":"string"},"delivery_id":{"type":"string"},"image_url":{"type":"string","format":"uri"},"mobile":{"type":"string"},"name":{"type":"string"}}},"agent_details":{"allOf":[{"$ref":"#/components/schemas/Agent"},{"description":"Present when status is AGENCY_ASSIGNED, ASSIGNED, PICKUP, PICKEDUP, DROPOFF, or DROPEDOFF"}]},"agency_details":{"allOf":[{"$ref":"#/components/schemas/AgencyDetails"},{"description":"Present when status is AGENCY_ASSIGNED, ASSIGNED, PICKUP, PICKEDUP, DROPOFF, or DROPEDOFF"}]},"vehicle_details":{"allOf":[{"$ref":"#/components/schemas/Vehicle"},{"description":"Present when status is AGENCY_ASSIGNED, ASSIGNED, PICKUP, PICKEDUP, DROPOFF, or DROPEDOFF"}]}}}}},"required":["success","code","message","responses"]},"Location":{"description":"Location object for pickup or dropoff in a delivery or estimate request","type":"object","properties":{"type":{"type":"string","description":"Values:\n  * `LATLNG` - Longitude and latitude values. Submitted as lat and lng in DeliveryLocation object\n  * `GHPOST` - Ghana Post GPS value. Submitted in value key in DeliveryLocation object\n  * `WHATTW` - What3Words value, Submitted in value key in DeliveryLocation object"},"value":{"type":"string","description":"Holds the value for either GHPOST or WHATTW"},"contact":{"$ref":"#/components/schemas/Contact"},"country_code":{"type":"string","description":"Iso Alpha-2 code for the delivery location country. Visit [country code ](https://www.iban.com/country-codes) for more reference","default":"GH"},"lat":{"type":"number","description":"Latitude value for delviery location if type is LATLNG","default":null},"lng":{"type":"number","description":"Longitude value for delviery location if type is LATLNG","default":null},"location":{"type":"string","description":"Human readable location of a delivery (address)","default":null}},"required":["type","contact","country_code"]},"Contact":{"description":"Contact person for the delivery location","type":"object","properties":{"name":{"type":"string","description":"Contact Person's Name","default":null},"mobile":{"type":"string","description":"Contact Person's Mobile Number"},"email":{"type":"string","description":"Contact Person's Email","default":null}},"required":["mobile"]},"Price":{"type":"object","properties":{"discount":{"type":"number","default":0},"value":{"type":"number","default":0},"currency_code":{"type":"string","default":"GHS","description":"Country Currency Code"},"currency_symbol":{"type":"string","default":"₵","description":"Country Currency Symbol"},"currency_name":{"type":"string","default":"Ghanaian cedi","description":"Country Currency Name"}},"required":["discount","value","currency_code","currency_name","currency_symbol"]},"Item":{"type":"object","description":"Object Structure for item in items array","properties":{"itemName":{"type":"string","description":"Name of item being shipped"},"itemQuantity":{"type":"number","description":"Quantity of the item being shipped"},"itemCost":{"type":"number","description":"Cost of the item being shipped"},"description":{"type":"string","default":null,"description":"A short description of the item"},"itemImages":{"type":"array","items":{"type":"string","description":"valid image url"}},"itemWeight":{"type":"number","description":"Package Weight","default":null},"is_fragile":{"type":"boolean","default":false},"dimensions":{"type":"object","description":"Dimensions of the item. Default to null","default":null,"properties":{"x":{"type":"number","description":"Length of the item"},"y":{"type":"number","description":"Width of the item"},"z":{"type":"number","description":"Height of the item"}},"required":["x","y","z"]}},"required":["itemName","itemCost","itemQuantity","itemWeight"]},"Agent":{"type":"object","properties":{"agent_first_name":{"type":"string"},"agent_last_name":{"type":"string"},"agent_mobile":{"type":"string"},"agent_picture":{"type":"string","description":"Image url"},"license_type":{"type":"string"},"license_number":{"type":"string"},"license_expiry":{"type":"number","description":"timestamp date of expiry date of license."}}},"AgencyDetails":{"type":"object","properties":{"name":{"type":"string","default":"Agency Name","description":"Agency Name"},"mobile_number":{"type":"string","default":23350484565,"description":"Agency Mobile Number"},"logo":{"type":"string","description":"Agency Logo Url"},"rating":{"type":"number","description":"Agency Rating"},"location":{"type":"object","properties":{"country_code":{"type":"string","default":"GH"},"latitude":{"type":"number","default":0},"longitude":{"type":"number","default":0},"city":{"type":"string"},"country":{"type":"string"}}}},"required":["name","mobile","logo","rating"]},"Vehicle":{"type":"object","properties":{"_id":{"type":"string"},"assigned_agent_id":{"type":"string","nullable":true},"brand":{"type":"string"},"model":{"type":"string"},"color":{"type":"string"},"picture":{"type":"string","format":"uri"},"vehicle_type":{"type":"string"},"license_plate_number":{"type":"string"},"latest_location":{"$ref":"#/components/schemas/LatestLocation"}}},"LatestLocation":{"description":"Latest Location of a rider or a vehicle","type":"object","properties":{"latitude":{"type":"number","format":"float"},"longitude":{"type":"number","format":"float"},"coordinates":{"type":"array","items":{"type":"number"}},"time":{"type":"integer","description":"Epoch timestamp in milliseconds"},"location":{"type":"string"},"state":{"type":"string"},"direction":{"type":"integer"},"speed":{"type":"number"}}}}}}
```