---
title: "Subscribe to parcel update notifications."
method: POST
path: "/v1/webhooks"
tags: ["webhooks"]
---

# Subscribe to parcel update notifications.

`POST /v1/webhooks`

## Request

- Base URL: `https://logistics.api.cabify-sandbox.com`
- URL: `https://logistics.api.cabify-sandbox.com/v1/webhooks`
- Auth: HTTP bearer

Register a webhook to receive real-time notifications when parcels are updated.

**Securing your webhook endpoint:**
1. Include a custom authorization header in the subscription request. Our API will forward
   it with every notification:
   ```
   Authorization: Bearer <your-auth-token>
   ```
2. For enhanced security using OAuth (client credentials), contact us to set up authentication
   with a `clientId` and `clientSecret`.

## Request body

- WebhookSubscription
  - `hook` 'parcel' | 'parcelLocation' | 'proofCodeGenerated', required: The event type to subscribe to: - `parcel`: Triggered on every parcel status change. - `parcelLocation`: Triggered when the driver's location is updated. - `proofCodeGenerated`: Triggered when a proof of delivery code is generated for a parcel.
  - `callback_url` string, uri, required: Your endpoint URL. The API will send a POST request to this URL each time the subscribed event occurs.
  - `headers` Header[]: Custom headers to include in every webhook request sent to your endpoint (e.g. for authentication).
    - `name` string, required: Header name
    - `value` string, required: Header value

## Response `201`

Webhook subscription created successfully.

## Other responses

- `400`: Bad request. One or more fields failed validation.
- `401`: Unauthorized. Missing or invalid authentication token.
- `429`: Too many requests. This API is rate limited per account and per endpoint. A 429 is an expected condition rather than a failed request: back off and retry it. The limits are not the same for every endpoint and can change, so handle the status instead of hard-coding a rate. See the Limits and reliability guide.

---

[API](https://skmtc.dev/cabify/apis/cabify-logistics-api.md) - [All operations](https://skmtc.dev/cabify/apis/cabify-logistics-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cabify/apis/cabify-logistics-api/revisions/dff49457aac9?raw)