Webhooks

Fery sends events to the webhookURL provided in Create Order.

That URL is saved on the ride. The same URL is used for:

ride status updates
partner location updates

Registering the webhook

There is no separate webhook registration API.

Host an HTTPS endpoint
Pass it as webhookURL in create order
Fery POSTs events to that URL for the ride

1 {
2   "webhookURL": "https://your-domain.com/fery/updates",
3   "metadata": {
4     "partnerOrderId": "DMRC-ORDER-1001"
5   }
6 }

Endpoint requirements

Requirement	Value
Method	`POST`
Body	JSON
Auth header	`secretkey: <WEBHOOK_SECRET>`
Success response	HTTP `200` or `201`

Case A — Status update

Sent when the ride status changes.

Identify this case when status is not location_updated.

Status values

`status`	Meaning
`accepted`	Partner confirmed the ride
`arrived`	Partner arrived at pickup
`started`	Trip started
`dropped`	Trip completed
`customer_cancelled`	Cancelled by customer via Cancel API
`rydr_cancelled`	Cancelled by partner
`expired`	No partner found
`aborted`	Cancelled operationally by the system

Example — `accepted`

1 {
2   "orderId": "1717235676225158",
3   "status": "accepted",
4   "otp": "1234",
5   "metadata": {
6     "partnerOrderId": "DMRC-ORDER-1001"
7   },
8   "captainDetails": {
9     "name": "Priya",
10     "mobile": "9888888888",
11     "currentVehicle": {
12       "number": "DL1SAA0001"
13     }
14   }
15 }

Example — `dropped`

1 {
2   "orderId": "1717235676225158",
3   "status": "dropped",
4   "amount": 52,
5   "distanceTravelled": 2.1,
6   "travelDuration": 12,
7   "dropTime": "2026-08-27T08:30:00.000Z",
8   "metadata": {
9     "partnerOrderId": "DMRC-ORDER-1001"
10   }
11 }

Fields

Field	Type	Description
`orderId`	string	Order id from create order
`status`	string	Status value from the table above
`metadata`	object	Present when sent on create order
`otp`	string	Ride OTP, when applicable
`eta`	number	ETA in minutes, when applicable
`captainDetails`	object	Partner details when available
`location`	object	Optional coordinates on some status events
`amount`	number	Fare amount when applicable
`reason`	string	Reason for cancel / expiry when applicable
`distanceTravelled`	number	When available
`travelDuration`	number	When available
`dropTime`	string	Completion time when available

captainDetails shape:

1 {
2   "name": "Priya",
3   "mobile": "9888888888",
4   "currentVehicle": {
5     "number": "DL1SAA0001"
6   }
7 }

Case B — Location update

Sent when partner location is updated for an active ride.

Identify this case when status is location_updated.

Example

1 {
2   "orderId": "1717235676225158",
3   "status": "location_updated",
4   "location": {
5     "latitude": 28.46102,
6     "longitude": 77.07411
7   },
8   "timestamp": 1756281000000,
9   "metadata": {
10     "partnerOrderId": "DMRC-ORDER-1001"
11   }
12 }

Fields

Field	Type	Required	Description
`orderId`	string	yes	Order id
`status`	string	yes	Always `location_updated`
`location.latitude`	number	yes	Partner latitude
`location.longitude`	number	yes	Partner longitude
`timestamp`	number	no	Event timestamp
`metadata`	object	no	From create order when present

Handling both cases

if status == "location_updated":
  handle location update
else:
  handle ride status update

Headers sent by Fery

1 Content-Type: application/json
2 secretkey: <WEBHOOK_SECRET>

Webhooks

Registering the webhook

Endpoint requirements

Case A — Status update

Status values

Example — accepted

Example — dropped

Fields

Case B — Location update

Example

Fields

Handling both cases

Headers sent by Fery

Example — `accepted`

Example — `dropped`