openapi: 3.1.0
info:
  title: Webhooks Specification
  version: '2024.1'
  description: >
    The Scurri Webhooks specification outlines the kinds 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: Tracking
    description: Webhooks related to tracking
webhooks:
  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:
      type: object
      properties:
        event_type:
          type: string
          description: The type of event that triggered the webhook.
          example: tracking_update
        event_id:
          type: string
          description: A unique identifier for the event.
          example: AB12C3
        payload_version:
          type: string
          example: '2024.1'
          description: The version of the payload schema.
    Event:
      type: object
      properties:
        status:
          type: string
          maxLength: 25
          description: >-
            The status Scurri assigns to the tracking event, in capitalized
            format.
          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
      properties:
        tracking_number:
          type: string
          description: The tracking number the tracking update is associated with.
          example: JD014600003281234567
        consignment_identifier:
          type: string
          maxLength: 255
          description: >-
            The identifier of the consignment to which this tracking update
            applies.
          example: ab12345
        consignment_number:
          type: string
          maxLength: 255
          description: >-
            The consignment number of the consignment to which this tracking
            update applies.
          example: JD014600003281234567
        order_number:
          type: string
          description: >-
            The order number of the consignment to which this tracking update
            applies.
          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'
