openapi: 3.0.0
info:
  description: 'Welcome to the Cabify Logistics API. This API allows you to create and manage parcel deliveries, track their status in real time, configure proof of delivery options, and receive live updates via webhooks. All requests must be authenticated using a Bearer token.

    '
  version: 1.0.0
  title: Cabify Logistics delivery webhooks API
  contact:
    email: p.delivery@cabify.com
servers:
- url: https://logistics.api.cabify.com
  description: Production
- url: https://logistics.api.cabify-sandbox.com
  description: Sandbox
tags:
- name: webhooks
  description: 'Subscribe to event-driven notifications to receive live updates about parcel status changes, location updates, and proof of delivery codes.

    '
paths:
  /v1/webhooks/{hook}:
    delete:
      tags:
      - webhooks
      summary: Unsubscribe from a webhook.
      description: Removes the webhook subscription for the specified event type.
      operationId: deleteWebhook
      parameters:
      - in: path
        name: hook
        description: The event type to unsubscribe from.
        required: true
        schema:
          type: string
          enum:
          - parcel
          - parcelLocation
          - proofCodeGenerated
      responses:
        '200':
          description: Webhook subscription removed successfully.
        '401':
          description: Unauthorized. Missing or invalid authentication token.
      security:
      - bearer_token: []
  /v1/webhooks:
    get:
      tags:
      - webhooks
      summary: List your active webhook subscriptions.
      description: Returns all active webhook subscriptions registered for your account.
      operationId: getWebhook
      responses:
        '200':
          description: Webhook subscriptions retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseWebhookSubscriptions'
        '401':
          description: Unauthorized. Missing or invalid authentication token.
      security:
      - bearer_token: []
    post:
      tags:
      - webhooks
      summary: Subscribe to parcel update notifications.
      description: "Register a webhook to receive real-time notifications when parcels are updated.\n\n**Securing your webhook endpoint:**\n1. Include a custom authorization header in the subscription request. Our API will forward\n   it with every notification:\n   ```\n   Authorization: Bearer <your-auth-token>\n   ```\n2. For enhanced security using OAuth (client credentials), contact us to set up authentication\n   with a `clientId` and `clientSecret`.\n"
      operationId: subscribeWebhook
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookSubscription'
        description: The webhook subscription details, including the event type and your callback URL.
        required: true
      responses:
        '201':
          description: Webhook subscription created successfully.
        '400':
          description: Bad request. One or more fields failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestError'
        '401':
          description: Unauthorized. Missing or invalid authentication token.
      security:
      - bearer_token: []
      callbacks:
        parcel:
          '{$request.body#/callback_url}':
            post:
              parameters:
              - in: header
                name: '{$request.body#/headers/name}'
                schema:
                  type: string
              - in: header
                name: '{$request.body#/headers/value}'
                schema:
                  type: string
              requestBody:
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/ParcelStatusHook'
              responses:
                '200':
                  description: Success
        parcelLocation:
          '{$request.body#/callback_url}':
            post:
              parameters:
              - in: header
                name: '{$request.body#/headers/name}'
                schema:
                  type: string
              - in: header
                name: '{$request.body#/headers/value}'
                schema:
                  type: string
              requestBody:
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/ParcelLocation'
              responses:
                '200':
                  description: Success
        proofCodeGenerated:
          '{$request.body#/callback_url}':
            post:
              parameters:
              - in: header
                name: '{$request.body#/headers/name}'
                schema:
                  type: string
              - in: header
                name: '{$request.body#/headers/value}'
                schema:
                  type: string
              requestBody:
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/ProofCodeGenerated'
              responses:
                '200':
                  description: Success
components:
  schemas:
    AssetKind:
      type: string
      description: The type of vehicle assigned to carry the parcel.
      enum:
      - bicycle
      - car
      - moped
      - scooter
      - van
    ResponseWebhookSubscription:
      type: object
      required:
      - id
      - callback_url
      - hook
      properties:
        id:
          type: number
          description: Internal identifier of the webhook subscription.
        hook:
          type: string
          enum:
          - parcel
          description: The event type this subscription listens to. Receive a notification for every individual parcel status change.
        callback_url:
          type: string
          format: uri
          example: http://example.com/your/callback/here
          description: Your endpoint URL. The API will send a POST request to this URL each time the subscribed event occurs.
        headers:
          type: array
          items:
            $ref: '#/components/schemas/Header'
          description: Custom headers included in every webhook request (e.g. for authentication).
    PickupFailed:
      type: object
      description: '**Deprecated.** Use `pickup_attempt` instead. Details of a failed pickup attempt.

        '
      properties:
        reason:
          type: string
          description: 'Reason why the pickup failed. See [pickup failed reasons](https://developers.cabify.com/reference/parcel-information#pickup-failed-reason) for a description of each value.

            '
          enum:
          - sender_no_show
          - sender_too_late
          - address_wrong
          - address_not_found
          - address_unsafe
          - parcel_suspicious
          - parcel_packaging
          - parcel_too_big_or_heavy
          - payment_requested
          - payment_fake
          - other_with_feedback
          - place_closed
          - delivery_not_found
          - already_picked_up
          - delivery_cancelled
          example: address_wrong
        failed_at:
          type: string
          format: date-time
          description: Timestamp of the failed pickup event, formatted according to RFC 3339, section 5.6.
          example: '2021-12-02T10:12:07.753Z'
        driver_comments:
          type: string
          description: Comments left by the driver explaining why the pickup failed.
          example: can't find the address
    ParcelStatusHook:
      type: object
      description: Payload sent to your webhook callback URL whenever a parcel's status changes.
      properties:
        id:
          type: string
          format: uuid
          description: System-generated UUID for this parcel.
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        external_id:
          type: string
          description: Your own identifier for this parcel, as provided when the parcel was created.
          example: parcel_001
        event_time:
          type: string
          format: date-time
          description: Timestamp when the parcel state change occurred, formatted according to RFC 3339, section 5.6.
          example: '2021-12-02T10:12:07.753Z'
        state:
          type: string
          description: 'The current lifecycle state of the parcel. See [parcel states](https://developers.cabify.com/reference/logistics-introduction#parcel) for a full description of each value.

            '
          enum:
          - ready
          - qualifiedforpickup
          - pickingup
          - intransit
          - delivering
          - delivered
          - returning
          - returned
          - incident
          - requestercancel
          - internalcancel
          - pickupfailed
          - onroutetopickup
          - readytopickup
          - onroutetofinalhub
          - receivedonfinalhub
          - readytodispatch
          - onroutetodelivery
          - undelivered
          - onroutetoreturn
          - returnrejected
        failure_reason:
          type: string
          description: 'If present, indicates why the delivery was rejected. See [failure reasons](https://developers.cabify.com/reference/parcel-information#failure-reason) for a description of each value.

            '
          enum:
          - unknown
          - payment_method_declined
          - no_payment_methods
          - requester_not_found_or_unauthorized
          - product_does_not_exist
          - invalid_pick_up_location
          - delivery_already_exist
        delivery_attempt:
          type: object
          properties:
            id_proof_of_delivery:
              type: object
              nullable: true
              properties:
                recipient_name:
                  type: string
                  description: Name of the person who received the parcel.
                  example: Francisco
                recipient_id_number:
                  type: string
                  example: 11111111T
                  description: Identity document number of the person who received the parcel.
            photo_proof_of_delivery:
              type: object
              nullable: true
              properties:
                photo_urls:
                  type: array
                  items:
                    type: string
                  description: List of URLs of the photos taken by the driver as proof of delivery.
                photo_url:
                  type: string
                  example: https://s3.amazon.com/photo.jpg
                  description: URL of the first photo taken by the driver as proof of delivery. Deprecated — use `photo_urls` instead.
            comment_proof_of_delivery:
              type: object
              nullable: true
              properties:
                comment:
                  type: string
                  example: El paquete se ha dejado en la puerta
                  description: Comment left by the driver as proof of delivery.
            fail_reason:
              type: string
              description: 'Reason the delivery attempt failed. See [delivery attempt fail reasons](https://developers.cabify.com/reference/parcel-information#delivery-attempt-fail-reason) for a description of each value.

                '
              enum:
              - recipient_not_found
              - rejected
              - wrong_address
              - zone_unsafe
              - invalid_proof
              - other
              - invalid
              - parcel_lost
              - parcel_unreadable_barcode
              - parcel_damaged
              - parcel_stolen
              - no_delivery_attempt
              - postponed_by_customer
              - place_closed
              - no_keyword
              - fraud_suspected
              - unknown
            support_ticket:
              type: string
              nullable: true
              description: ID of the support ticket opened by the driver when an incident occurs.
            address:
              type: string
              nullable: true
              description: Address where the delivery was attempted.
            feedback:
              type: string
              nullable: true
              description: Feedback provided by the driver when the parcel could not be delivered.
        tracking:
          type: object
          nullable: true
          properties:
            eta_to_accept:
              type: integer
              nullable: true
              description: Estimated time in seconds until a driver is assigned to this delivery.
              example: 90
            location:
              type: object
              nullable: true
              properties:
                lat:
                  type: number
                  format: float
                  example: 40.4489254
                lon:
                  type: number
                  format: float
                  example: -3.6730293
            routes:
              type: object
              properties:
                pick_up:
                  description: Information about the route from the driver position to the pickup point. Available before the parcel has been picked up.
                  allOf:
                  - $ref: '#/components/schemas/ParcelStatusRoute'
                drop_off:
                  description: Information about the route from the pickup point to the drop-off destination.
                  allOf:
                  - $ref: '#/components/schemas/ParcelStatusRoute'
            tracking_url:
              type: string
              description: Public URL where the parcel's live tracking can be viewed.
        asset:
          $ref: '#/components/schemas/Asset'
        driver:
          type: object
          nullable: true
          description: Information about the assigned driver. Only present once a driver has been assigned.
          properties:
            photo_url:
              type: string
              description: URL of the driver's profile photo.
              example: https://s3.amazon.com/photo.jpg
            name:
              type: string
              description: Driver's full name.
              example: Pepe
            phone:
              type: string
              description: Driver's contact phone number.
              example: '+34658478854'
        pickup_failed:
          deprecated: true
          allOf:
          - $ref: '#/components/schemas/PickupFailed'
        pickup_attempt:
          $ref: '#/components/schemas/PickupAttempt'
    CommentProofOfPickUp:
      type: object
      description: Written note left by the driver as confirmation of the pickup.
      properties:
        comment:
          type: string
          description: Comment left by the driver at the time of pickup.
    ParcelStatusRoute:
      type: object
      description: Route information between two points during a delivery.
      required:
      - eta
      - path
      properties:
        eta:
          type: integer
          example: 120
          description: Estimated time of arrival in seconds.
        path:
          type: string
          example: fhdsa98fha87sdfhas76dgf8a
          description: Encoded polyline representing the route path.
    ParcelLocation:
      type: object
      description: Payload sent to your webhook callback URL with the driver's real-time location.
      required:
      - parcel_id
      - location
      - state
      properties:
        parcel_id:
          type: string
          format: uuid
          description: UUID of the parcel being tracked.
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        external_id:
          type: string
          description: Your own identifier for this parcel, as provided when the parcel was created.
          example: parcel_001
        location:
          type: object
          description: Current location of the driver carrying the parcel.
          required:
          - latitude
          - longitude
          properties:
            latitude:
              type: number
              format: float
              description: Latitude in decimal degrees.
              example: 40.4489254
            longitude:
              type: number
              format: float
              description: Longitude in decimal degrees.
              example: -3.6730293
        state:
          type: string
          description: Indicates whether the driver is on the way to collect the parcel or has already picked it up.
          enum:
          - onroutetopickup
          - intransit
    Header:
      type: object
      required:
      - name
      - value
      properties:
        name:
          type: string
          description: Header name
          example: Authorization
        value:
          type: string
          description: Header value
          example: Bearer 000111222333444
    WebhookSubscription:
      type: object
      required:
      - callback_url
      - hook
      properties:
        hook:
          type: string
          enum:
          - parcel
          - parcelLocation
          - proofCodeGenerated
          description: '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:
          type: string
          format: uri
          example: http://example.com/your/callback/here
          description: Your endpoint URL. The API will send a POST request to this URL each time the subscribed event occurs.
        headers:
          type: array
          items:
            $ref: '#/components/schemas/Header'
          description: Custom headers to include in every webhook request sent to your endpoint (e.g. for authentication).
    RequestError:
      type: object
      description: Standard error response body returned when a request fails.
      required:
      - errors
      properties:
        errors:
          type: array
          description: List of human-readable error messages describing what went wrong.
          items:
            type: string
    PickupAttempt:
      type: object
      description: Details of a pickup attempt, whether successful or not.
      required:
      - status
      - attempted_at
      - address
      properties:
        fail_reason:
          type: string
          description: 'If the attempt was unsuccessful, the reason why it failed. See [pickup failed reasons](https://developers.cabify.com/reference/parcel-information#pickup-failed-reason) for a description of each value.

            '
          enum:
          - sender_no_show
          - sender_too_late
          - address_wrong
          - address_not_found
          - address_unsafe
          - parcel_suspicious
          - parcel_packaging
          - parcel_too_big_or_heavy
          - payment_requested
          - payment_fake
          - other_with_feedback
          - place_closed
          - delivery_not_found
          - already_picked_up
          - delivery_cancelled
        status:
          type: string
          description: Outcome of the pickup attempt.
          enum:
          - PickupAttemptStatusPickedUp
          - PickupAttemptStatusPickupFailed
        attempted_at:
          type: string
          format: date-time
          description: Timestamp of the pickup attempt, formatted according to RFC 3339, section 5.6.
          example: '2021-12-02T10:12:07.753Z'
        address:
          type: string
          description: Address where the pickup attempt was made.
          example: Calle de la Princesa, 1, 28008 Madrid
        feedback:
          type: string
          description: Comments left by the driver about the pickup attempt.
          example: can't find the address
        photo_proof_of_pickup:
          $ref: '#/components/schemas/PhotoProofOfPickUp'
        comment_proof_of_pickup:
          $ref: '#/components/schemas/CommentProofOfPickUp'
    PhotoProofOfPickUp:
      type: object
      description: Photo evidence captured by the driver at the pickup location.
      properties:
        photo_urls:
          type: array
          description: List of URLs to the photos taken by the driver during pickup.
          items:
            type: string
            format: url
    ResponseWebhookSubscriptions:
      type: object
      required:
      - subscriptions
      properties:
        subscriptions:
          type: array
          items:
            $ref: '#/components/schemas/ResponseWebhookSubscription'
    Asset:
      type: object
      description: Details of the vehicle assigned to the delivery.
      properties:
        reg_plate:
          type: string
          nullable: true
          description: Vehicle registration plate number.
          example: 1111AAA
        name:
          type: string
          description: Vehicle model name.
          example: Audi A3
        color:
          type: string
          description: Vehicle color.
          example: black
        asset_kind:
          $ref: '#/components/schemas/AssetKind'
    ProofCodeGenerated:
      type: object
      description: Payload sent to your webhook callback when a proof of delivery code is generated for a parcel.
      required:
      - parcel_id
      - code
      properties:
        parcel_id:
          type: string
          format: uuid
          description: UUID of the parcel this code was generated for.
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        code:
          type: string
          description: Four-digit code generated for the delivery. The recipient must provide this code to the driver to confirm receipt.
          example: '1234'
  securitySchemes:
    bearer_token:
      type: http
      scheme: bearer