> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.feryrides.co.in/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.feryrides.co.in/_mcp/server.

# Webhooks

> Status and location events Fery sends to your webhookURL

# 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.

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

```json
{
  "webhookURL": "https://your-domain.com/fery/updates",
  "metadata": {
    "partnerOrderId": "DMRC-ORDER-1001"
  }
}
```

## 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`

```json
{
  "orderId": "1717235676225158",
  "status": "accepted",
  "otp": "1234",
  "metadata": {
    "partnerOrderId": "DMRC-ORDER-1001"
  },
  "captainDetails": {
    "name": "Priya",
    "mobile": "9888888888",
    "currentVehicle": {
      "number": "DL1SAA0001"
    }
  }
}
```

### Example — `dropped`

```json
{
  "orderId": "1717235676225158",
  "status": "dropped",
  "amount": 52,
  "distanceTravelled": 2.1,
  "travelDuration": 12,
  "dropTime": "2026-08-27T08:30:00.000Z",
  "metadata": {
    "partnerOrderId": "DMRC-ORDER-1001"
  }
}
```

### 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:

```json
{
  "name": "Priya",
  "mobile": "9888888888",
  "currentVehicle": {
    "number": "DL1SAA0001"
  }
}
```

---

## Case B — Location update

Sent when partner location is updated for an active ride.

Identify this case when `status` is `location_updated`.

### Example

```json
{
  "orderId": "1717235676225158",
  "status": "location_updated",
  "location": {
    "latitude": 28.46102,
    "longitude": 77.07411
  },
  "timestamp": 1756281000000,
  "metadata": {
    "partnerOrderId": "DMRC-ORDER-1001"
  }
}
```

### 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

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

## Headers sent by Fery

```http
Content-Type: application/json
secretkey: <WEBHOOK_SECRET>
```