{"openapi":"3.0.0","x-samples-languages":["curl","javascript","node","java","kotlin","python","php","go","swift"],"info":{"version":"v1.0","title":"Webhooks API 1.0","x-hugo-values":{"tags":["api"],"categories":["Webhooks"],"public":true,"weight":80}},"paths":{"/":{"post":{"tags":["Webhooks"],"summary":"Register webhook endpoint","description":"This endpoint is used to register an external endpoint to receive webhook events from Karhoo. Note that the URL supplied **must** support https.\n","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequest"}}},"description":"request body","required":true},"responses":{"201":{"description":"Subscription created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"}}}},"400":{"$ref":"#/components/responses/400InvalidInput"},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"500":{"$ref":"#/components/responses/500InternalServerErr"},"502":{"$ref":"#/components/responses/502BadGateway"}},"security":[{"Bearer":[]}]},"get":{"tags":["Webhooks"],"summary":"Returns active subscriptions for the user","description":"Returns the current subscriptions for the user\n","responses":{"200":{"description":"A list of active subscriptions for this account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionResponse"}}}},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"404":{"$ref":"#/components/responses/404NotFound"},"500":{"$ref":"#/components/responses/500InternalServerErr"},"502":{"$ref":"#/components/responses/502BadGateway"}},"security":[{"Bearer":[]}]},"delete":{"tags":["Webhooks"],"summary":"Removes active subscriptions or delete by ID.","description":"The endpoint removes the active subscriptions of an authenticated user or deletes the specific subscription by ID if provided.\n","parameters":[{"name":"subscription_id","in":"query","required":false,"description":"The ID of the subscription to delete, if not supplied ALL active subscriptions for the organizations will be deleted","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The subscription removed successfully"},"401":{"$ref":"#/components/responses/401Unauthorized"},"403":{"$ref":"#/components/responses/403Forbidden"},"404":{"$ref":"#/components/responses/404NotFound"},"500":{"$ref":"#/components/responses/500InternalServerErr"},"502":{"$ref":"#/components/responses/502BadGateway"}},"security":[{"Bearer":[]}]}}},"servers":[{"url":"https://rest.sandbox.karhoo.com/v1/webhooks"}],"components":{"responses":{"400InvalidInput":{"description":"Bad Request. The request was invalid.","content":{"*/*":{"schema":{"type":"object","properties":{"code":{"type":"string","example":"K0002","description":"Error number"},"message":{"type":"string","example":"Invalid request payload","description":"Details of the error"}}}}}},"401Unauthorized":{"description":"Unauthorized. The request requires user authentication (not logged in).","content":{"*/*":{"schema":{"type":"object","properties":{"code":{"type":"string","example":"K6001","description":"Error number"},"message":{"type":"string","example":"Could not authenticate","description":"Details of the error"}}}}}},"403Forbidden":{"description":"Forbidden. The credentials provided do not have sufficient authority for this request. Please request access by emailing [API Support](api@karhoo.com?subject=API%20Access%20Request).","content":{"*/*":{"schema":{"type":"object","properties":{"code":{"type":"string","example":"K0005","description":"Error number"},"message":{"type":"string","example":"Missing required role for this request","description":"Details of the error"}}}}}},"404NotFound":{"description":"Not found. Subscription not found, or following information is not available anymore.","content":{"*/*":{"schema":{"type":"object","description":"Details of the error that occurred whilst processing the request","required":["code","message"],"properties":{"code":{"type":"string","description":"Internally generated code for this error","example":"K4003"},"message":{"type":"string","description":"Details of the actual error","example":"Could not find a subscription"}}}}}},"500InternalServerErr":{"description":"Internal server error. Something has gone wrong on the website's server, but the server could not be more specific on what the exact problem is.","content":{"*/*":{"schema":{"type":"object","properties":{"code":{"type":"string","example":"K0001","description":"Error number"},"message":{"type":"string","example":"General request error","description":"Details of the error"}}}}}},"502BadGateway":{"description":"Bad Gateway. The server, which was acting as a gateway or proxy, received an invalid response from the upstream server.","content":{"*/*":{"schema":{"type":"object","properties":{"code":{"type":"string","example":"K0000","description":"Error number"},"message":{"type":"string","example":"Bad Gateway error","description":"Details of the error"}}}}}}},"securitySchemes":{"Bearer":{"description":"To access all endpoints in this API a valid Bearer Token must be passed in the 'Authorization' header.\nA Bearer Token is generated by the /v1/auth/token API.\n
The following syntax must be used in the 'Authorization' header :\n`Bearer: xxxxxx.yyyyyyy.zzzzzz`","type":"apiKey","name":"Authorization","in":"header"}},"schemas":{"SubscriptionRequest":{"type":"object","description":"Specifies a demand partner's host parameters to receive Karhoo events","required":["url","shared_secret"],"properties":{"url":{"type":"string","description":"Demand partner's endpoint","example":"https://your-company.com/karhoo/events"},"shared_secret":{"type":"string","minLength":10,"description":"The shared secret to sign requests from Karhoo side","example":"dontT3llAnyoneThisSecret!"},"topics":{"type":"array","items":{"type":"string","enum":["TripStatus","DriverDetails","FinalFare","DriverPositionChanged","FleetChanged"]},"description":"The topics the subscription should subscribe to. Available topics are TripStatus, DriverDetails, FinalFare, FleetChanged and DriverPositionChanged. If not provided the subscription will be created with the following default topics TripStatus, DriverDetails, FinalFare.","example":["TripStatus","DriverPositionChanged"]}}},"SubscriptionResponse":{"type":"object","description":"List of subscriptions","properties":{"url":{"type":"string","description":"-- DEPRECATED -- Demand partner's endpoint of the most recently added subscription","example":"https://your-company.com/karhoo/events"},"topics":{"type":"array","items":{"type":"string"},"description":"-- DEPRECATED -- The topics active for the most recently added subscription","example":["TripStatus","DriverPositionChanged"]},"subscriptions":{"type":"array","description":"The list of subscriptions","items":{"$ref":"#/components/schemas/Subscription"},"example":[{"url":"https://your-company.com/karhoo/events","topics":["DriverDetails"],"id":"15c11af2-b0cd-415e-a9c7-2ddfeaff6b3f"},{"url":"https://your-company.com/karhoo/otherevents","topics":["TripStatus","FinalFare"],"id":"d8d31c4c-485d-43da-9e38-191566ee27d7"}]}}},"Subscription":{"type":"object","description":"Contains subscription parameters","properties":{"url":{"type":"string","description":"Demand partner's endpoint","example":"https://your-company.com/karhoo/events"},"topics":{"type":"array","items":{"type":"string"},"description":"The topics active for this subscription","example":["TripStatus","DriverPositionChanged"]},"id":{"type":"string","description":"The subscription ID","format":"uuid"}},"example":{"url":"https://your-company.com/karhoo/events","topics":["DriverDetails"],"id":"15c11af2-b0cd-415e-a9c7-2ddfeaff6b3f"}},"Event":{"description":"Event sent to demand pertner's endpoint","type":"object","required":["id","event_type","sent_at","checksum","attempt_number","data"],"properties":{"id":{"type":"string","format":"uuid"},"event_type":{"type":"string","example":"trip.status"},"sent_at":{"type":"string","format":"date-time","example":"2024-04-17T10:29:51.728Z"},"checksum":{"type":"string","description":"A hex-encoded checksum of the payload information to assist the caller in determining if the event contains new information."},"attempt_number":{"type":"number","format":"int32","description":"Our record of attempts to push this event starting at 0 to signify success on the first send. Attempts greater than 0 indicates the current retry attempt number."},"data":{"type":"string","description":"The event payload. Serialised JSON string, of one of the following types:\n\n * TripStatus - Emitted when the state of a trip has updated, e.g. when the driver has arrived, passenger is on board, the trip has completed, etc.\n * DriverDetails - Information about the vehicle driver.\n * FinalFareReleased - Notification that the final fare has been set for this trip\n * DriverPositionChanged - GPS location of the driver for this trip.\n * FleetChanged - Notification that the fleet for this trip has been changed.\n"}}},"TripStatus":{"type":"object","description":"Trip status event payload with Karhoo's trip ID and the current status of the request.","properties":{"trip_id":{"type":"string","format":"uuid","description":"Karhoo's trip ID"},"partner_traveller_id":{"type":"string","description":"Partner's own ID that can be passed at booking time, that can be used to correlate webhook events"},"status":{"$ref":"#/components/schemas/State"},"cancellation_reason":{"$ref":"#/components/schemas/CancellationReason"},"state_details":{"$ref":"#/components/schemas/StateDetails"}}},"State":{"type":"string","description":"The status of the Request:\n\n - COMPLETED: Passenger has reached their destination.
\n - DRIVER_EN_ROUTE: A driver is \"en route\" to the start location. This state can occur multiple times in case of a driver re-assignment.
\n - CONFIRMED: The Request has been accepted by Dispatch.
\n - ARRIVED: The driver has arrived. This state might be skipped in some cases.
\n - NO_DRIVERS_AVAILABLE: The request was unfulfilled because no driver was available.
\n - POB: Passenger is in the vehicle and the ride has \"started\".
\n - DRIVER_CANCELLED: The Request has been cancelled by the driver.
\n - BOOKER_CANCELLED: The Request has been cancelled by the rider.
\n - KARHOO_CANCELLED: The Request has been cancelled by Karhoo.
\n - FAILED: There was an internal error with the booking.
\n - PREAUTH_DECLINED: There was an issue with payment preauth and Karhoo is investigating it.
\n
\n","enum":["COMPLETED","DRIVER_EN_ROUTE","CONFIRMED","ARRIVED","POB","NO_DRIVERS_AVAILABLE","DRIVER_CANCELLED","BOOKER_CANCELLED","KARHOO_CANCELLED","FAILED","PREAUTH_DECLINED"],"example":"CONFIRMED"},"CancellationReason":{"type":"string","description":"The reason for the cancellation of the trip. We have three separate cancellation reason groups, depending on who cancelled the trip:\nFor driver cancellations:\n\n - OTHER_DISPATCH_REASON
\n - REQUESTED_BY_USER
\n - PASSENGER_DIDNT_SHOW_UP
\n - DRIVER_CANCELED
\n - SUPPLIER_CANCELLED
\n - DISPATCH_CANCELLED
\n - NO_AVAILABILITY_IN_THE_AREA
\n - NO_FEE
\n - DECLINED_BOOKING
\n
\nFor booker cancellations: \n\n - OTHER_USER_REASON
\n - DRIVER_DIDNT_SHOW_UP
\n - ETA_TOO_LONG
\n - DRIVER_IS_LATE
\n - CAN_NOT_FIND_VEHICLE
\n - NOT_NEEDED_ANYMORE
\n - ASKED_BY_DRIVER_TO_CANCEL
\n - FOUND_BETTER_PRICE
\n - NOT_CLEAR_MEETING_INSTRUCTIONS
\n - COULD_NOT_CONTACT_CARRIER
\n
\nFor Karhoo cancellations:\n\n - OTHER_KARHOO_REASON
\n - FRAUD
\n - NO_AVAILABILITY
\n - ASKED_BY_USER
\n - ASKED_BY_DISPATCH
\n - ASKED_BY_DRIVER
\n - FAILURE
\n - PREAUTH_FAILED
\n - REBOOK
\n - ERROR_DURING_BOOKING
\n
\n","enum":["OTHER_DISPATCH_REASON","REQUESTED_BY_USER","PASSENGER_DIDNT_SHOW_UP","DRIVER_CANCELED","SUPPLIER_CANCELLED","DISPATCH_CANCELLED","NO_AVAILABILITY_IN_THE_AREA","NO_FEE","DECLINED_BOOKING","OTHER_USER_REASON","DRIVER_DIDNT_SHOW_UP","ETA_TOO_LONG","DRIVER_IS_LATE","CAN_NOT_FIND_VEHICLE","NOT_NEEDED_ANYMORE","ASKED_BY_DRIVER_TO_CANCEL","FOUND_BETTER_PRICE","NOT_CLEAR_MEETING_INSTRUCTIONS","COULD_NOT_CONTACT_CARRIER","OTHER_KARHOO_REASON","FRAUD","NO_AVAILABILITY","ASKED_BY_USER","ASKED_BY_DISPATCH","ASKED_BY_DRIVER","FAILURE","PREAUTH_FAILED","REBOOK","ERROR_DURING_BOOKING"],"example":"REQUESTED_BY_PASSENGER"},"DriverDetails":{"type":"object","description":"Details of the driver and vehicle that will service this Booking","required":["trip_id","vehicle_class","vehicle_license_plate","driver"],"properties":{"trip_id":{"type":"string","format":"uuid","description":"Karhoo's trip ID"},"vehicle_class":{"type":"string","description":"Vehicle category","example":"MPV"},"description":{"type":"string","description":"Make, model and colour of vehicle","example":"Renault Scenic (Black)"},"passenger_capacity":{"type":"number","format":"int32","example":3},"luggage_capacity":{"type":"number","format":"int32","example":2},"vehicle_license_plate":{"type":"string","description":"Vehicle's licence plate value","example":"123 XYZ"},"driver":{"$ref":"#/components/schemas/Driver"},"partner_traveller_id":{"type":"string","description":"Partner's own ID that can be passed at booking time, that can be used to correlate webhook events"},"make":{"type":"string","description":"Make of vehicle","example":"Renault"},"model":{"type":"string","description":"Model of vehicle","example":"Scenic"},"colour":{"type":"string","description":"Colour of vehicle","example":"BLACK"},"tags":{"type":"array","items":{"type":"string"},"description":"A set of vehicle's attributes","example":["child-seat","electric"]}}},"Driver":{"type":"object","description":"Details of the vehicle's driver","required":["first_name","last_name","phone_number"],"properties":{"first_name":{"type":"string","description":"Driver's first name","example":"Michael"},"last_name":{"type":"string","description":"Driver's last name","example":"Higgins"},"phone_number":{"type":"string","description":"Driver's contact phone number","example":"+441111111111"},"photo_url":{"type":"string","description":"URL to retrieve driver's photo","example":"https://karhoo.com/drivers/mydriver.png"},"license_number":{"type":"string","description":"Driver's licence number","example":"ZXZ151YTY"}}},"FinalFareReleased":{"type":"object","description":"Notification that the final fare for this trip has been set. See Fares API for more information https://developer.karhoo.com/reference#final-fare","properties":{"trip_id":{"type":"string","format":"uuid","description":"Karhoo's trip ID"},"partner_traveller_id":{"type":"string","description":"Partner's own ID that can be passed at booking time, that can be used to correlate webhook events"}}},"DriverPositionChanged":{"type":"object","description":"GPS location of the driver for this trip.","properties":{"trip_id":{"type":"string","format":"uuid","description":"Karhoo's trip ID"},"latitude":{"type":"number","format":"double","description":"latest driver position latitude"},"longitude":{"type":"number","format":"double","description":"latest driver position longitude"},"heading":{"type":"number","format":"integer","description":"Vehicle direction (compass degrees)"}}},"FleetChanged":{"type":"object","description":"Notification that the fleet for this trip has been changed.","required":["trip_id","new_fleet_name"],"properties":{"trip_id":{"type":"string","format":"uuid","description":"Karhoo's trip ID"},"new_fleet_name":{"type":"string","description":"The new fleet name"},"new_driver":{"$ref":"#/components/schemas/Driver"},"new_vehicle_class":{"type":"string","description":"Vehicle category","example":"MPV"},"new_vehicle_license_plate":{"type":"string","description":"Vehicle's licence plate value","example":"123 XYZ"},"new_vehicle_luggage_capacity":{"type":"number","format":"int32","example":2},"new_vehicle_passenger_capacity":{"type":"number","format":"int32","example":3}}},"StateDetails":{"type":"string","description":"Additional information about the state of the Trip.\nThis field is optional and currently only presents in DRIVER_EN_ROUTE trip state. \n\n - FOLLOW_ON - driver is finishing previous trip before coming to passenger
\n
\n","enum":["FOLLOW_ON"],"example":"FOLLOW_ON"}}},"x-readme":{"explorer-enabled":true,"proxy-enabled":true}}