Webhooks

Explanation of the JSON Webhook Data Structure

The provided JSON payload represents the structure of a webhook callback for delivery updates. Each component serves a distinct purpose, ensuring that delivery details, pricing, contacts, and tracking information are communicated efficiently. Here's a breakdown of the content without specific values:

Root-Level Fields:

  1. success: A boolean value indicating whether the webhook call was successful. Typically, this is true if no errors occurred in the process.

  2. code: Represents the HTTP status code, such as 200, confirming the server's response status.

  3. message: A descriptive string providing context for the webhook, such as a title or explanation of the callback event.

  4. responses: This is the main payload object or array containing all relevant delivery details.

Pickup Information (pickup):

  • value: Represents a unique identifier or description of the pickup location.

  • country_code: A two-letter ISO code representing the country of the pickup point.

  • lat & lng: The geographic latitude and longitude of the pickup location for mapping and geolocation purposes.

  • type: Specifies the type of location, such as coordinates (LATLNG) or a named address.

  • location: A textual representation of the pickup address or area.

  • contact: An object detailing the individual associated with the pickup:

    • name: Full name of the contact person.

    • mobile: Phone number for communication.

    • email: Email address, if available.

Dropoff Information (dropoff):

  • Similar to pickup, this section describes the destination details:

    • Includes location data (lat, lng, type, etc.) and the contact's information (name, mobile, email).

Pricing Details (full_price):

  • discount: The amount of any applied discount.

  • value: The total delivery cost after discounts.

  • currency_code: A three-letter ISO currency code (e.g., GHS for Ghanaian Cedis).

  • currency_symbol & currency_name: Visual and textual representations of the currency.

Contact Information (contact):

  • Contains the primary contact details for the delivery:

    • name, mobile, email: Reflects the sender or recipient’s information.

Delivery Metadata:

  1. return_delivery: A boolean indicating whether this is a return delivery.

  2. return_reason: A reason for the return, if applicable.

  3. distance: The total delivery distance, often used for pricing calculations.

  4. individual_pricing_id: A unique identifier for the pricing structure applied to this delivery.

  5. timestamp: A Unix epoch timestamp recording the event time.

  6. status: Current state of the delivery (e.g., pending, assigned, completed).

  7. instructions: Any special instructions related to the delivery.

  8. reference: A unique identifier for referencing the delivery.

  9. start_time & end_time: Define the delivery time window in Unix epoch format.

  10. time_completed: Indicates the exact completion time, if applicable.

Item Details (items):

  • An array containing objects that describe each item in the delivery:

    • itemName: Name of the item being delivered.

    • itemIcon: A URL linking to an icon representing the item.

    • itemQuantity: Number of units of the item.

    • itemCost & itemPrice: Base and transactional prices.

    • currency_code: ISO code for the item's currency.

    • description: Detailed description of the item.

    • itemWeight: Weight of the item, often used for logistics.

    • dimensions: The physical dimensions (length, width, height).

    • itemImages: URLs linking to item images.

Tracking and Delivery Codes:

  • tracking_code: A unique code used to track the delivery.

  • delivery_code: Code specific to the delivery for backend referencing.

  • secret_code: Used for secure verification at the dropoff point.

Agent Details (agent_details):

  • agent_email & agent_mobile: Contact details of the assigned delivery agent.

  • agent_picture: URL linking to the agent’s profile picture.

  • agent_first_name & agent_last_name: The agent's full name.

Agency Details (agency_details):

  • name: Name of the agency handling the delivery.

  • logo: A URL linking to the agency's logo.

  • mobile_number & email: Contact details of the agency.

Additional Links:

  1. tracking_link: URL for the customer to track the delivery status.

  2. waybill_link: URL to access the delivery waybill, containing formal documentation.

This structure ensures that all critical aspects of the delivery process are captured and communicated effectively, allowing for seamless integration and real-time updates. NOTE: Agent Details are only available when a rider is assigned to the delivery and that is delivery status assigned,pickup, pickedup, dropoff, droppedoff,ended

```json
{
  "success": true,
  "code": 200,
  "message": "Delivery Update Callback",
  "responses": {
    "pickup": {
      "value": "<string>",
      "country_code": "<string>",
      "lat": 5.5954647,
      "lng": -0.2426031,
      "type": "<string>",
      "location": "<string>",
      "contact": {
        "name": "<string>",
        "mobile": "<string>",
        "email": "<string>"
      }
    },
    "dropoff": {
      "value": "<string>",
      "country_code": "<string>",
      "lat": 5.55928,
      "lng": -0.1974306,
      "type": "<string>",
      "location": "<string>",
      "contact": {
        "name": "<string>",
        "mobile": "<string>",
        "email": "<string>"
      }
    },
    "return_contact": {
      "coordinates": []
    },
    "full_price": {
      "discount": 0,
      "value": 13,
      "currency_code": "<string>",
      "currency_symbol": "<string>",
      "currency_name": "<string>"
    },
    "contact": {
      "name": "<string>",
      "email": "<string>",
      "mobile": "<string>"
    },
    "return_delivery": false,
    "return_reason": null,
    "distance": 6.42,
    "individual_pricing_id": "<string>",
    "timestamp": 1733936947997,
    "status": "<string>",
    "instructions": "<string>",
    "reference": "<string>",
    "start_time": 1733990400000,
    "end_time": 1734022800000,
    "time_completed": null,
    "items": [
      {
        "itemName": "<string>",
        "itemIcon": "<string>",
        "itemQuantity": 1,
        "itemCost": 6000,
        "itemPrice": 0,
        "currency_code": "<string>",
        "currency_name": "<string>",
        "currency_symbol": "<string>",
        "collect_item_price": false,
        "description": "<string>",
        "itemImage": "<string>",
        "itemImages": [
          "<string>"
        ],
        "itemWeight": 0.05,
        "item_weight": null,
        "item_weight_id": null,
        "is_fragile": false,
        "dimensions": {
          "size_id": null,
          "item_size_name": null,
          "length": 1,
          "width": 1,
          "height": 1,
          "x": 1,
          "y": 1,
          "z": 1
        },
        "category_id": null
      }
    ],
    "tracking_code": "<string>",
    "delivery_code": "<string>",
    "secret_code": "<string>",
    "createdAt": "<ISO Date>",
    "updatedAt": "<ISO Date?",
    "agent_details": {
      "agent_email": "<string>",
      "agent_picture": "<string>",
      "rating": 4.6,
      "agent_first_name": "<string>",
      "agent_last_name": "<string>",
      "agent_mobile": "<string>"
    },
    "agency_details": {
      "name": "<string>",
      "logo": "<string>",
      "mobile_number": "<string>",
      "email": "<string>"
    },
    "tracking_link": "https://sandboxtracking.swoovedelivery.com/details?tracking_code=",
    "waybill_link": "https://sandboxwaybill.swoovedelivery.com/?deliveries="
  }
}
```
PreviousFund Wallet

Last updated

Was this helpful?