openapi: 3.1.0
info:
  title: Webhooks Specification
  version: '2025.1'
  description: >
    The Scurri Webhooks specification outlines the types of events for which
    webhooks can be triggered from the Scurri platform.

    Each definition includes a description of when an event is triggered and the
    payload that will be sent to the configured endpoint.


    Configuration of webhooks can be managed via the webhooks dashboard on the
    Scurri UI.
tags:
  - name: Consignments
    description: >
      Scurri supports sending Webhook notifications for specific consignment
      lifecycle events, allowing your system to react immediately to updates.


      Currently, the following event is supported:

      - Proof of Delivery (POD): Triggered when Scurri successfully retrieves a
      proof of delivery document from a carrier.

      Please refer to the sections below for detailed payload specifications.
  - name: Tracking
    description: >
      Scurri supports sending Webhook notifications for specific tracking
      lifecycle events, allowing your system to react immediately to updates.


      Currently, the following event is supported:

      - Tracking Update: Triggered when Scurri processes tracking updates
      received from carriers.

      Please refer to the sections below for detailed payload specifications.
webhooks:
  ProofOfDelivery:
    description: >
      This event occurs when Scurri retrieves a digital Proof of Delivery
      document. 

      The payload includes a direct link to retrieve the file, and extra
      consignment related information.
    post:
      operationId: proof_of_delivery_update
      summary: Proof of Delivery
      tags:
        - Consignments
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProofOfDeliveryResponse'
      responses:
        '200':
          description: Return a 200 response to acknowledge receipt of the webhook.
  TrackingUpdate:
    description: >
      A webhook that is triggered when one or more tracking updates are received
      from the carrier.
    post:
      operationId: tracking_update
      summary: Tracking Update
      tags:
        - Tracking
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReceivedTrackingUpdates'
      responses:
        '200':
          description: Return a 200 response to acknowledge receipt of the webhook.
components:
  schemas:
    WebhookStandardFields:
      required:
        - event_type
        - event_id
        - payload_version
      type: object
      properties:
        event_type:
          type: string
          description: The type of event that triggered the webhook.
          maxLength: 255
          example: proof_of_delivery
        event_id:
          type: string
          description: A unique identifier for the event.
          example: AB12C3
        payload_version:
          type: string
          example: '2025.1'
          maxLength: 10
          description: The version of the payload schema.
    ProofOfDeliveryResponse:
      allOf:
        - $ref: '#/components/schemas/WebhookStandardFields'
        - type: object
          properties:
            payload:
              $ref: '#/components/schemas/ProofOfDeliveryDocuments'
    ProofOfDeliveryDocuments:
      type: array
      items:
        $ref: '#/components/schemas/ProofOfDeliveryDocument'
    ProofOfDeliveryDocument:
      type: object
      description: >-
        Proof of delivery document details (image or signature). Always linked
        to a consignment; linked to a package if supported by the carrier.
      required:
        - document_id
        - document_url
        - file_type
        - proof_of_delivery_type
        - consignment_identifier
        - order_number
        - carrier
        - service_id
      properties:
        document_id:
          type: string
          description: The unique identifier for the proof of delivery document.
          example: AB12C3
        document_url:
          type: string
          format: uri
          description: >-
            A time-limited URL to retrieve the proof of delivery document. The
            link remains active for 72 hours.
          example: >-
            https://example.com/storage/document-with-unique-name.pdf?signature=sample-signature
        file_type:
          type: string
          description: The file type of the proof of delivery document.
          enum:
            - image/jpeg
            - image/png
            - application/pdf
            - image/svg+xml
          example: image/jpeg
        proof_of_delivery_type:
          type: string
          description: The type of proof of delivery (e.g., image, signature).
          maxLength: 9
          enum:
            - image
            - signature
          example: signature
        consignment_identifier:
          type: string
          description: The identifier of the consignment.
          example: '2154321'
          maxLength: 255
        order_number:
          type: string
          description: The order number of the consignment.
          example: order-12345
          maxLength: 255
        package_tracking_number:
          type: string
          description: >-
            Package tracking number. Optional; populated only if included by the
            carrier with the proof of delivery.
          example: JD014600003281234567
          maxLength: 50
        package_reference:
          type: string
          description: The reference for the package.
          example: ref-12345
          maxLength: 255
        carrier:
          type: string
          description: The name of the carrier who shipped the consignment.
          example: DHL
          maxLength: 64
        service_id:
          type: string
          description: Service identifier (e.g., carrier and service name).
          maxLength: 128
          example: Generic Carrier|Next Day
    Event:
      type: object
      required:
        - timestamp
        - status
      properties:
        status:
          type: string
          maxLength: 25
          description: The status Scurri assigns to the tracking event.
          example: DELIVERED
        description:
          type: string
          maxLength: 500
          description: A description of the tracking event.
          example: The package was delivered to the recipient.
        timestamp:
          type: string
          description: The timestamp when the tracking event occurred.
          example: '2025-10-01T14:30:00'
        carrier_code:
          type: string
          maxLength: 50
          description: The event code provided by the carrier.
          example: EVD
        location:
          type: string
          maxLength: 255
          description: The location where the event took place.
          example: London
    Events:
      type: array
      items:
        $ref: '#/components/schemas/Event'
    TrackingUpdate:
      type: object
      required:
        - tracking_number
        - consignment_identifier
        - consignment_number
        - order_number
        - id
        - carrier
        - events
      properties:
        tracking_number:
          type: string
          description: >-
            The tracking number of the package the tracking update is associated
            with.
          maxLength: 50
          example: JD014600003281234567
        consignment_identifier:
          type: string
          maxLength: 255
          description: The identifier of the consignment.
          example: ab12345
        consignment_number:
          type: string
          maxLength: 255
          description: The consignment number of the consignment.
          example: '000000000008108293'
        order_number:
          type: string
          description: The order number of the consignment.
          example: order-12345
        id:
          type: integer
          description: The internal parcel identifier from our tracking system.
          example: 1234567890
        carrier:
          type: string
          maxLength: 50
          description: The name of the carrier who provided this tracking update.
          example: DHL
        events:
          $ref: '#/components/schemas/Events'
    TrackingUpdates:
      type: array
      items:
        $ref: '#/components/schemas/TrackingUpdate'
    ReceivedTrackingUpdates:
      allOf:
        - $ref: '#/components/schemas/WebhookStandardFields'
        - type: object
          properties:
            carrier_slug:
              type: string
              maxLength: 50
              description: The slug of the carrier that provided the tracking update.
              example: dhl
            count:
              type: integer
              description: The number of packages (tracking updates) in the response.
              example: 1
            trackings:
              $ref: '#/components/schemas/TrackingUpdates'
