---
agentTools:
  projectIndex: https://kosmo.readme.io/llms.txt
---

# /v2/webhooks/kosmo

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "contact": {
      "email": "developer@kosmo.delivery",
      "name": "Kosmo API Support"
    },
    "description": "Kosmo API Reference v2",
    "termsOfService": "https://www.kosmo.delivery/",
    "title": "Kosmo API Reference v2",
    "version": "2.0"
  },
  "paths": {
    "/v2/webhooks/kosmo": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookPayload"
              }
            }
          },
          "description": "Webhook request body",
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "tags": [
          "Webhooks"
        ]
      }
    }
  },
  "servers": [
    {
      "url": "https://api.kosmo.delivery",
      "description": "Kosmo API URL"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "token"
      }
    },
    "schemas": {
      "DriverModel": {
        "required": [
          "fullname",
          "phone"
        ],
        "properties": {
          "id": {
            "description": "The id of the driver.",
            "type": "string",
            "example": "driver_123456"
          },
          "fullname": {
            "description": "The name of the driver if available.",
            "type": "string",
            "example": "John Doe"
          },
          "phone": {
            "description": "The phone number of the driver if available.",
            "type": "string",
            "example": "+6512345678"
          },
          "email": {
            "description": "The email of the driver if available.",
            "type": "string"
          },
          "plateNumber": {
            "description": "The plate number of the vehicle if available.",
            "type": "string",
            "example": "SG123456789"
          },
          "photoURL": {
            "description": "The photo URL of the driver if available.",
            "type": "string",
            "example": "https://example.com/driver.jpg"
          },
          "location": {
            "description": "Current driver's location.",
            "$ref": "#/components/schemas/Coordinates"
          }
        }
      },
      "OrderStatus": {
        "description": "This represents the order status. Read more about order statuses under the \"List Deliveries\" section.",
        "enum": [
          "submitted",
          "created",
          "to_pickup",
          "picked_up",
          "delivered",
          "failed",
          "cancelled",
          "returning",
          "returned",
          "at_hub",
          "to_dropoff"
        ],
        "type": "string"
      },
      "Money": {
        "description": "Details of money.",
        "properties": {
          "amount": {
            "description": "Amount of money in cents.",
            "type": "integer",
            "example": 1000
          },
          "currency": {
            "description": "Currency of the amount.",
            "type": "string",
            "example": "SGD"
          }
        },
        "required": [
          "amount",
          "currency"
        ],
        "example": {
          "amount": 1480,
          "currency": "SGD"
        }
      },
      "WebhookType": {
        "description": "Webhook type",
        "type": "string",
        "enum": [
          "stop_status_update",
          "route_status_update"
        ]
      },
      "BaseWebhookPayload": {
        "description": "Base Webhook payload",
        "type": "object",
        "required": [
          "eventId",
          "eventType",
          "orderId",
          "deliveryId",
          "timestamp",
          "signature"
        ],
        "properties": {
          "eventId": {
            "description": "The event id",
            "type": "string",
            "example": "5f9b9b9b-9b9b-9b9b-9b9b-9b9b9b9b9b9b"
          },
          "eventType": {
            "$ref": "#/components/schemas/WebhookType"
          },
          "orderId": {
            "description": "This is the Kosmo order id.",
            "type": "string",
            "example": "SG-1234567890"
          },
          "deliveryId": {
            "description": "The id of the provider delivery",
            "type": "string",
            "example": "PANDAGO-1234567890"
          },
          "provider": {
            "description": "The provider name",
            "type": "string",
            "example": "PANDAGO"
          },
          "timestamp": {
            "description": "The timestamp of the event",
            "type": "string",
            "format": "RFC3339",
            "example": "2022-12-30T23:30:00.000Z"
          },
          "ts": {
            "description": "The timestamp of the event in microseconds",
            "type": "integer",
            "example": 1723108376000000
          },
          "signature": {
            "description": "The signature of the payload",
            "type": "string",
            "example": "lLQvCgsRcNUsP9EGdPYW8YgRZPUqmscAhc1Pqa89lrk="
          }
        }
      },
      "RouteStatusUpdateWebhookPayload": {
        "allOf": [
          {
            "$ref": "#/components/schemas/BaseWebhookPayload"
          },
          {
            "type": "object",
            "required": [
              "orderStatus",
              "statusHistory",
              "totalAmount",
              "provider"
            ],
            "properties": {
              "orderStatus": {
                "$ref": "#/components/schemas/OrderStatus"
              },
              "driver": {
                "$ref": "#/components/schemas/DriverModel"
              },
              "pickupStartEta": {
                "description": "Estimated time of pick up provided in RFC3339. This is the earliest time the order can be picked up. Can be empty.",
                "type": "string",
                "format": "RFC3339",
                "example": "2020-01-01T00:00:00.000Z"
              },
              "pickupEta": {
                "description": "Estimated time of pick up provided in RFC3339. This is the latest time the order can be picked up. Can be empty.",
                "type": "string",
                "format": "RFC3339",
                "example": "2020-01-01T00:00:00.000Z"
              },
              "dropoffEta": {
                "description": "The estimated time of arrival for the dropoff.",
                "type": "string",
                "format": "RFC3339",
                "example": "2022-12-30T23:30:00.000Z"
              },
              "statusHistory": {
                "description": "(soon) The status history of the order.",
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/StatusHistory"
                }
              },
              "trackingURL": {
                "description": "Tracking URL with complete information such as payment and all recipients.",
                "type": "string",
                "example": "https://tracking.kosmo.delivery/tracking/demo/"
              },
              "providerTrackingURL": {
                "description": "Tracking URL with complete information such as payment and all recipients.",
                "type": "string",
                "example": "https://provider.delivery/tracking/demo/"
              },
              "proofOfDeliveryURLs": {
                "description": "Deprecated - use proofs. The proof of delivery URLs by order reference id. This will be provided if available.",
                "type": "object",
                "additionalProperties": {
                  "type": "string",
                  "example": "http://provider.delivery/proof/30303-4344"
                }
              },
              "proofs": {
                "description": "The proof of pickup and delivery URLs by order reference id. This will be provided if available. Lasts for 7 days.",
                "type": "object",
                "additionalProperties": {
                  "$ref": "#/components/schemas/Proofs"
                }
              },
              "waybillURL": {
                "description": "URL link to the waybills for printing. Each unique parcel will require one unique waybill label.",
                "type": "string",
                "example": "https://share.kosmo.delivery/waybill_staging/213d102c-3457-43e8-859e-a2933c0c9946.pdf"
              },
              "cancellationReason": {
                "description": "The reason for cancellation.",
                "type": "string",
                "example": "Driver is slow"
              },
              "orderReferenceStatus": {
                "description": "The statuses of the order references. It's provided when the order is completed.",
                "type": "object",
                "additionalProperties": {
                  "$ref": "#/components/schemas/DropoffStatus"
                },
                "example": {
                  "ref1": "delivered",
                  "ref2": "canceled"
                }
              },
              "trackingIdRef": {
                "description": "Each delivery with your order reference id will have its tracking URL here.\nJust so you know: only this recipient information is provided, and not your payment information.\nIt will be mapped by Order Ref ID and it is suitable to share with your final customers.",
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "example": {
                  "ref1": "https://tracking.kosmo.delivery/tracking/demo/",
                  "ref2": "https://tracking.kosmo.delivery/tracking/demo/",
                  "ref3": "https://tracking.kosmo.delivery/tracking/demo/"
                }
              },
              "totalAmount": {
                "$ref": "#/components/schemas/Money"
              },
              "dropoffStatuses": {
                "description": "Statuses (and failure reason, failure reason note, note from driver if any) of the dropoffs. It's provided when the order's status changed.",
                "type": "object",
                "additionalProperties": {
                  "$ref": "#/components/schemas/DropoffStatusData"
                },
                "example": {
                  "ref1": {
                    "status": "delivered",
                    "failureReason": "",
                    "failureReasonNote": "",
                    "noteFromDriver": "Delivered to the receptionist"
                  },
                  "ref2": {
                    "status": "canceled",
                    "failureReason": "destination_unreachable",
                    "failureReasonNote": "",
                    "noteFromDriver": ""
                  },
                  "ref3": {
                    "status": "canceled",
                    "failureReason": "deliver_another_time",
                    "failureReasonNote": "Customer asked for delivery tomorrow",
                    "noteFromDriver": ""
                  }
                }
              }
            }
          }
        ]
      },
      "StopStatusUpdateWebhookPayload": {
        "allOf": [
          {
            "$ref": "#/components/schemas/BaseWebhookPayload"
          },
          {
            "type": "object",
            "required": [
              "orderReferenceId",
              "stopStatus"
            ],
            "properties": {
              "orderReferenceId": {
                "description": "You can provide this field to identify this dropoff with a specific ID in your system. So you will be able to track your system order in a case if you want to create multi dropoff order.",
                "type": "string",
                "example": "1aa3ce25-fb22-4f49-861e-118a500a26f2"
              },
              "orderStatus": {
                "$ref": "#/components/schemas/OrderStatus"
              },
              "driver": {
                "$ref": "#/components/schemas/DriverModel"
              },
              "pickupStartEta": {
                "description": "Estimated time of pick up provided in RFC3339. This is the earliest time the order can be picked up. Can be empty.",
                "type": "string",
                "format": "RFC3339",
                "example": "2020-01-01T00:00:00.000Z"
              },
              "pickupEta": {
                "description": "Estimated time of pick up provided in RFC3339. This is the latest time the order can be picked up. Can be empty.",
                "type": "string",
                "format": "RFC3339",
                "example": "2020-01-01T00:00:00.000Z"
              },
              "dropoffEta": {
                "description": "The estimated time of arrival for the dropoff.",
                "type": "string",
                "format": "RFC3339",
                "example": "2022-12-30T23:30:00.000Z"
              },
              "failureReason": {
                "$ref": "#/components/schemas/DropoffFailureReason"
              },
              "failureReasonNote": {
                "description": "The note of the failure reason if any.",
                "type": "string"
              },
              "stopStatus": {
                "$ref": "#/components/schemas/DropoffStatus"
              },
              "noteFromDriver": {
                "description": "The note from the driver if any.",
                "type": "string"
              },
              "proofs": {
                "description": "The proof of pickup and delivery URLs by order reference id. This will be provided if available. Lasts for 7 days.",
                "$ref": "#/components/schemas/Proofs"
              },
              "trackingURL": {
                "description": "URL to track the order.",
                "type": "string",
                "example": "https://tracking.kosmo.delivery/tracking/demo/"
              }
            }
          }
        ]
      },
      "WebhookPayload": {
        "description": "Webhook payload",
        "type": "object",
        "anyOf": [
          {
            "$ref": "#/components/schemas/BaseWebhookPayload"
          },
          {
            "$ref": "#/components/schemas/StopStatusUpdateWebhookPayload"
          },
          {
            "$ref": "#/components/schemas/RouteStatusUpdateWebhookPayload"
          }
        ]
      },
      "StatusHistory": {
        "description": "Status history of the order.",
        "type": "object",
        "properties": {
          "status": {
            "$ref": "#/components/schemas/OrderStatus"
          },
          "timestamp": {
            "description": "The timestamp of the event.",
            "type": "string",
            "format": "RFC3339",
            "example": "2022-12-30T23:30:00.000Z"
          }
        }
      },
      "Coordinates": {
        "type": "object",
        "required": [
          "lat",
          "lng"
        ],
        "properties": {
          "lat": {
            "description": "Latitude.",
            "type": "number",
            "example": 1.234567,
            "x-go-type": "float64"
          },
          "lng": {
            "description": "Longitude.",
            "type": "number",
            "example": 103.234567,
            "x-go-type": "float64"
          }
        }
      },
      "DropoffStatusData": {
        "type": "object",
        "properties": {
          "status": {
            "$ref": "#/components/schemas/DropoffStatus"
          },
          "failureReason": {
            "$ref": "#/components/schemas/DropoffFailureReason"
          },
          "failureReasonNote": {
            "description": "The note of the failure reason if any.",
            "type": "string"
          },
          "noteFromDriver": {
            "description": "The note from the driver if any.",
            "type": "string"
          },
          "completedAt": {
            "description": "The timestamp of delivery or failure.",
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "DropoffStatus": {
        "type": "string",
        "description": "The status of the dropoff.",
        "enum": [
          "delivered",
          "canceled",
          "to_dropoff",
          "returning",
          "returned"
        ],
        "example": "delivered"
      },
      "DropoffFailureReason": {
        "type": "string",
        "description": "Failure reason if any.",
        "enum": [
          "incorrect_missing_item",
          "deliver_another_time",
          "destination_unreachable",
          "recipient_unavailable",
          "unable_to_find_customer",
          "other"
        ]
      },
      "Proofs": {
        "type": "object",
        "required": [
          "proofsOfPickup",
          "proofsOfDelivery"
        ],
        "properties": {
          "proofsOfPickup": {
            "description": "The proof of pickup URLs by order reference id. This will be provided if available.",
            "type": "array",
            "items": {
              "type": "string",
              "example": "http://provider.delivery/proof/pickup/30303-4344"
            }
          },
          "proofsOfDelivery": {
            "description": "The proof of delivery URLs by order reference id. This will be provided if available.",
            "type": "array",
            "items": {
              "type": "string",
              "example": "http://provider.delivery/proof/delivery/30303-4344"
            }
          }
        }
      }
    }
  },
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true,
    "samples-enabled": true
  },
  "_id": {
    "buffer": {
      "0": 99,
      "1": 136,
      "2": 86,
      "3": 191,
      "4": 139,
      "5": 245,
      "6": 189,
      "7": 0,
      "8": 16,
      "9": 17,
      "10": 176,
      "11": 113
    }
  }
}
```