openapi: 3.2.0
info:
  title: Shipcloud Webhooks API
  version: '1.0'
  contact:
    name: Developer Support
    email: developers@shipcloud.io
  termsOfService: https://www.shipcloud.io/en/terms-and-conditions
  description: 'Operations tagged Webhooks across 2 of this provider''s published API definitions: shipcloud_v1_oai3.json, shipcloud-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.shipcloud.io/v1
security:
- basic_auth: []
tags:
- name: Webhooks
paths:
  /webhooks:
    get:
      description: Get a list of previously created webhooks
      responses:
        '200':
          description: A list of webhooks.
          content:
            application/json:
              schema:
                type: object
                properties:
                  webhooks:
                    type: array
                    items:
                      $ref: '#/components/schemas/webhook_object_with_id'
              examples:
                Getting all webhooks:
                  $ref: '#/components/examples/webhooks_list_example'
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Interval:
              $ref: '#/components/headers/RateLimit-Interval'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            X-Request-ID:
              $ref: '#/components/headers/shicloud-Request-ID'
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
      tags:
      - Webhooks
      summary: Get webhooks
      x-summary-source: derived
      operationId: getWebhooks
      x-operation-id-source: derived
    post:
      description: Creating a webhook on the shipcloud platform
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/webhook_create_with_basic_auth'
            examples:
              Creating a basic webhook:
                $ref: '#/components/examples/webhook_create_request_object'
              Creating a tracking catch-all webhook:
                value:
                  url: https://example.com/webhook
                  event_types:
                  - shipment.tracking.*
              Creating a webhook with basic auth:
                $ref: '#/components/examples/webhook_create_request_object_basic_auth'
      responses:
        '200':
          description: A webhooks has been created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/webhook_object_with_id'
              examples:
                Webhook with ID response:
                  $ref: '#/components/examples/webhook_with_id_example'
                Webhook with basic auth response:
                  $ref: '#/components/examples/webhook_with_basic_auth_example'
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Interval:
              $ref: '#/components/headers/RateLimit-Interval'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            X-Request-ID:
              $ref: '#/components/headers/shicloud-Request-ID'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402'
        '403':
          $ref: '#/components/responses/403'
        '422':
          $ref: '#/components/responses/422'
        '500':
          $ref: '#/components/responses/500'
      tags:
      - Webhooks
      summary: Create webhooks
      x-summary-source: derived
      operationId: postWebhooks
      x-operation-id-source: derived
    servers:
    - url: https://api.shipcloud.io/v1
  /webhooks/{id}:
    parameters:
    - name: id
      in: path
      required: true
      description: a webhook identifier
      schema:
        type: string
    get:
      description: Returns a single webhook based on the provided id
      responses:
        '200':
          description: Detailed information about a single webhook
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/webhook_object_with_id'
              examples:
                Webhook with ID response:
                  $ref: '#/components/examples/webhook_with_id_example'
                Webhook with basic auth response:
                  $ref: '#/components/examples/webhook_with_basic_auth_example'
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Interval:
              $ref: '#/components/headers/RateLimit-Interval'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            X-Request-ID:
              $ref: '#/components/headers/shicloud-Request-ID'
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
      tags:
      - Webhooks
      summary: Get webhooks by id
      x-summary-source: derived
      operationId: getWebhooksById
      x-operation-id-source: derived
    delete:
      description: Deletes a single webhook identified by its id
      responses:
        '204':
          description: Webhook was deleted successfully
          content:
            application/json:
              examples:
                Empty response:
                  value: {}
        '401':
          $ref: '#/components/responses/401'
        '402':
          $ref: '#/components/responses/402'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
      tags:
      - Webhooks
      summary: Delete webhooks by id
      x-summary-source: derived
      operationId: deleteWebhooksById
      x-operation-id-source: derived
    servers:
    - url: https://api.shipcloud.io/v1
components:
  responses:
    '404':
      description: The api endpoint or ressource you were trying to reach can't be found.
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Interval:
          $ref: '#/components/headers/RateLimit-Interval'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/shicloud-Request-ID'
    '422':
      description: Your request was well-formed but couldn't be followed due to semantic errors. Please see the response body for more detailed information. A possible problem could be that you are not sending all the data that is required or data that is not necessary for this call.
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Interval:
          $ref: '#/components/headers/RateLimit-Interval'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/shicloud-Request-ID'
    '401':
      description: Something has gone wrong when authorizing with our API. Please check e.g. if you're trying to use your sandbox api key with an operation that can only be used with a live API key.
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Interval:
          $ref: '#/components/headers/RateLimit-Interval'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/shicloud-Request-ID'
    '403':
      description: You are not allowed to talk to this endpoint. This can either be due to a wrong authentication or when you're trying to reach an endpoint that your account isn't allowed to access.
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Interval:
          $ref: '#/components/headers/RateLimit-Interval'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/shicloud-Request-ID'
    '500':
      description: Something has seriously gone wrong. Don't worry, we'll have a look at it. If the error persists, please don't hesitate to contact us by sending us an email containing the `X-Request-ID` header we've returned.
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Interval:
          $ref: '#/components/headers/RateLimit-Interval'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/shicloud-Request-ID'
    '400':
      description: Your request was not correct. Please see the response body for more detailed information.
      content:
        application/json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  description: Strings that describe, what has gone wrong. We're tunnelling error responses from the carriers. When this is the case, we try to prefix an error with 'The carrier {xyz} returned the following error:'
                  type: string
          examples:
            Single error:
              value:
                errors:
                - simple error message
            Multiple errors:
              value:
                errors:
                - simple error message
                - another error message
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Interval:
          $ref: '#/components/headers/RateLimit-Interval'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/shicloud-Request-ID'
    '402':
      description: You've reached a maximum that is defined in your current plan. Please upgrade to a higher plan.
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Interval:
          $ref: '#/components/headers/RateLimit-Interval'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        X-Request-ID:
          $ref: '#/components/headers/shicloud-Request-ID'
  headers:
    RateLimit-Reset:
      description: The number of seconds that shows when the request rate limit resets (e.g. 42)
      schema:
        type: integer
    RateLimit-Interval:
      description: The number of seconds the interval for this user is long (e.g. 60)
      schema:
        type: integer
    RateLimit-Remaining:
      description: Remaining number of request in the current interval (e.g. 111)
      schema:
        type: integer
    shicloud-Request-ID:
      description: An internal identifier that we generate for every request. If you encounter a problem with your request, please send us this id when opening a support case.
      schema:
        type: string
    RateLimit-Limit:
      description: A number that shows the overall limit of requests this user can send (e.g. 120)
      schema:
        type: integer
  examples:
    webhook_with_basic_auth_example:
      value:
        id: e0ff4250-6c8e-494d-a069-afd9d566e372
        url: https://example.com/webhook
        event_types:
        - shipment.tracking.delayed
        - shipment.tracking.delivered
        deactivated: false
        security:
          type: basic_auth
    webhook_with_id_example:
      value:
        id: e0ff4250-6c8e-494d-a069-afd9d566e372
        url: https://example.com/webhook
        event_types:
        - shipment.tracking.delayed
        - shipment.tracking.delivered
        deactivated: false
    webhooks_list_example:
      value:
        webhooks:
        - id: 583cfd8b-77c7-4447-a3a0-1568bb9cc553
          url: https://example.com/webhook
          event_types:
          - shipment.tracking.*
          deactivated: false
        - id: e0ff4250-6c8e-494d-a069-afd9d566e372
          url: https://example.com/webhook
          event_types:
          - shipment.tracking.delayed
          - shipment.tracking.delivered
          deactivated: false
          security:
            type: basic_auth
    webhook_create_request_object_basic_auth:
      value:
        url: https://example.com/webhook
        event_types:
        - shipment.*
        security:
          type: basic_auth
          username: shipcloud_webhook_username
          password: Very$ecurePassw0rd
    webhook_create_request_object:
      value:
        url: https://example.com/webhook
        event_types:
        - shipment.tracking.delayed
        - shipment.tracking.delivered
  schemas:
    webhook_event_types:
      description: the event types that a webhook can have
      type: string
      enum:
      - '*'
      - shipment.*
      - shipment.status.*
      - shipment.status.deleted
      - shipment.tracking.*
      - shipment.tracking.awaits_pickup_by_receiver
      - shipment.tracking.canceled
      - shipment.tracking.delayed
      - shipment.tracking.delivered
      - shipment.tracking.destroyed
      - shipment.tracking.exception
      - shipment.tracking.label_created
      - shipment.tracking.not_delivered
      - shipment.tracking.notification
      - shipment.tracking.out_for_delivery
      - shipment.tracking.picked_up
      - shipment.tracking.transit
      - shipment.tracking.unknown
    webhook_create_with_basic_auth:
      allOf:
      - $ref: '#/components/schemas/webhook_object'
      - properties:
          security:
            type: object
            properties:
              username:
                type: string
                description: The username that should be used (for basic auth)
              password:
                type: string
                description: The password that should be used (for basic auth)
    webhook_object_with_id:
      allOf:
      - $ref: '#/components/schemas/webhook_object'
      - properties:
          id:
            type: string
            description: the webhook id that can be used for requesting info about a webhook
          deactivated:
            type: boolean
            description: set to true, if the call of the webhook URL fails ten times.
        required:
        - id
    webhook_object:
      type: object
      description: Webhooks inform your system of events that have happened within the shipcloud platform
      properties:
        url:
          type: string
          description: The URL that the webhook should call
        event_types:
          type: array
          description: Events this webhook should subscribe to
          items:
            $ref: '#/components/schemas/webhook_event_types'
        security:
          type: object
          description: Security object to hold data for securing the webhook
          properties:
            type:
              type: string
              description: Type of authorization
              enum:
              - basic_auth
      required:
      - url
      - event_types
  securitySchemes:
    basic_auth:
      type: http
      scheme: basic
externalDocs:
  description: Find more info at the shipcloud developer portal
  url: https://developers.shipcloud.io
x-refined-from:
- shipcloud_v1_oai3.json
- shipcloud-openapi.yml