Sendcloud Webhooks API

openapi: 3.2.0
info:
  title: Webhooks API
  version: 2.0.0
  description: Sendcloud is able to actively communicate updates in a parcel (such as updates in the delivery status) to your application using webhooks.
  contact:
    name: Sendcloud API Support
    url: https://www.sendcloud.dev
    email: contact@sendcloud.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://www.shop_url.com/webhook
  description: User API endpoint
security:
- Sendcloud-Signature: []
tags:
- name: Webhooks
paths: {}
webhooks:
  IntegrationConnected:
    post:
      operationId: sc-public-v2-webhooks-integration_connected
      summary: Integration connected
      description: A request is sent to the defined webhook whenever the integration is created within our system.
      x-mint:
        href: /api/v2/webhooks/integration-connected
        content: "<Warning>\n  **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3).\n</Warning>"
      tags:
      - Webhooks
      requestBody:
        description: Webhook data you will receive
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntegrationConnectedWebhook'
      responses:
        '200':
          $ref: '#/components/responses/200'
  IntegrationDeleted:
    post:
      operationId: sc-public-v2-webhooks-integration_deleted
      summary: Integration deleted
      description: A request is sent to the defined webhook whenever the integration is deleted from our system.
      x-mint:
        href: /api/v2/webhooks/integration-deleted
        content: "<Warning>\n  **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3).\n</Warning>"
      tags:
      - Webhooks
      requestBody:
        description: Webhook data you will receive
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntegrationDeletedWebhook'
      responses:
        '200':
          $ref: '#/components/responses/200'
  IntegrationModified:
    post:
      operationId: sc-public-v2-webhooks-integration_modified
      summary: Integration modified
      description: A request is sent to the defined webhook whenever the integration is updated.
      x-mint:
        href: /api/v2/webhooks/integration-modified
        content: "<Warning>\n  **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3).\n</Warning>"
      tags:
      - Webhooks
      requestBody:
        description: Webhook data you will receive
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IntegrationUpdatedWebhook'
      responses:
        '200':
          $ref: '#/components/responses/200'
  ParcelStatusChanged:
    post:
      operationId: sc-public-v2-webhooks-parcel_status_changed
      summary: Parcel status changed
      description: Happens whenever a parcel within this integration shifts to a different status.
      x-mint:
        href: /api/v2/webhooks/parcel-status-changed
        content: "<Warning>\n  **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3).\n</Warning>"
      tags:
      - Webhooks
      requestBody:
        description: Webhook data you will receive
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ParcelStatusChangedWebhook'
      responses:
        '200':
          $ref: '#/components/responses/200'
  ReturnCreated:
    post:
      operationId: sc-public-v2-webhooks-return_created
      summary: Return created
      description: Happens whenever a return is created from a parcel matching the integration.
      x-mint:
        href: /api/v2/webhooks/return-created
        content: "<Warning>\n  **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3).\n</Warning>"
      tags:
      - Webhooks
      requestBody:
        description: Webhook data you will receive
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReturnCreatedWebhook'
      responses:
        '200':
          $ref: '#/components/responses/200'
components:
  schemas:
    IntegrationDeletedWebhook:
      description: The webhook payload when an integration is deleted from Sendcloud
      type: object
      title: Webhook Integration Deleted Object
      allOf:
      - $ref: '#/components/schemas/IntegrationWebhookBase'
      - type: object
        properties:
          action:
            type: string
            example: integration_deleted
            enum:
            - integration_deleted
    IntegrationWebhookBase:
      description: Base schema for integration webhook payloads
      type: object
      properties:
        action:
          type: string
          description: Describes the webhook action
        timestamp:
          type: integer
          example: 1525271885993
        integration:
          type: object
          properties:
            id:
              type: integer
              format: int64
              example: 1
              minimum: 1
              description: A unique identifier for an integration within Sendcloud
            shop_name:
              type: string
              example: API Integration
              description: The integration name as configured under the [integration settings in Sendcloud](https://app.sendcloud.com/v2/settings/integrations/manage)
            shop_url:
              type: string
              format: uri
              example: https://www.sendcloud.com
              description: The integration url
            system:
              type: string
              example: api
              description: The integration type
            failing_since:
              type:
              - 'null'
              - string
              format: date-time
              example: '2019-02-03T06:48:07Z'
              description: A date time indicating when in time Sendcloud lost connection to the integration.
            last_fetch:
              type:
              - 'null'
              - string
              example: '2019-02-03T06:48:07Z'
              format: date-time
              description: A date time indicating when was the last successful order fetching.
            last_updated_at:
              type:
              - 'null'
              - string
              format: date-time
              example: '2019-02-03T06:48:07Z'
              description: A date time indicating when the integration settings were updated.
            service_point_enabled:
              type: boolean
              description: True if you have configured [service point](https://support.sendcloud.com/hc/en-us/articles/360026097951-FAQ-Service-Points) support for your integration.
            service_point_carriers:
              type: array
              uniqueItems: true
              description: The service point carriers configured for your integration
              items:
                type: string
            webhook_active:
              type: boolean
              description: True if you have enabled webhooks, False otherwise
            webhook_url:
              type: string
              description: Your integration URL to be used by Sendcloud to communicate with.
              format: uri
              example: https://www.sendcloud.com/sendcloud-webhooks
      required:
      - action
      - timestamp
    ParcelStatusChangedWebhook:
      type: object
      description: The webhook payload when a parcel (either an outgoing or an incoming one) changes status.
      title: Webhook Parcel Status Changed Object
      properties:
        action:
          type: string
          description: Describes the webhook action
          example: parcel_status_changed
          enum:
          - parcel_status_changed
        timestamp:
          type: number
          description: A unix timestamp indicating the time that the status changed
        carrier_status_change_timestamp:
          type: number
          nullable: true
          description: A unix timestamp indicating the time that the status changed in the carrier's system
        parcel:
          type: object
          description: Parcel object
          properties:
            id:
              type: integer
              description: Sendcloud unique identifier or the parcel
              example: 1
            name:
              type: string
              description: Sender name
              example: Mr Bob
            company_name:
              type: string
              description: Company name of the sender
              example: Sendcloud
            address:
              type: string
              description: Address of the sender
              example: Stadhuisplein 10
            address_divided:
              type: object
              description: Divided object of address
              properties:
                street:
                  type: string
                  description: Street name
                  example: Stadhuisplein
                house_number:
                  type: integer
                  description: House number
                  example: 10
            city:
              type: string
              description: City name
              example: Eindhoven
            postal_code:
              type: string
              description: Postal code
              example: 5611 EM
            telephone:
              type: string
              description: Telephone number of the contact person
              example: '612345678'
            email:
              type: string
              format: email
              description: An email address of the person this parcel is supposed to be delivered to
              example: contact@sendcloud.com
            date_created:
              type: string
              description: Date and time of when parcel created
              example: '2019-02-03T06:48:07'
            tracking_number:
              type: string
              description: Tracking number of the shipment
              example: 3SYZXG132912330
            weight:
              type: string
              description: Weight of the parcel
              example: '2.000'
            label:
              type: object
              description: "Labels array. More information in <a\n    href=\"https://www.sendcloud.com/shipping-label/\" target=\"_blank\">Labels</a>"
              properties:
                normal_printer:
                  type: array
                  items:
                    type: string
                    format: uri
                    example: https://panel.sendcloud.sc/api/v2/label/normal_printer/3172?start_from=0&hash=bbfd669ee9ebb19408b85b33d181a50040fd9bc4
                label_printer:
                  type: string
                  format: uri
                  example: https://panel.sendcloud.sc/api/v2/label/label_printer/3172?hash=bbfd669ee9ebb19408b85b33d181a50040fd9bc4
            customs_declaration:
              type: object
              description: An object with available printers that lists available links to the created customs declaration form. (deprecated in favour of documents)
            status:
              type: object
              description: An object containing an id and the name of the status.
              properties:
                id:
                  type: integer
                  example: 1
                  description: The Sendcloud unique identifier of the status
                message:
                  type: string
                  example: Ready to send
                  description: The description of the status
            data:
              type: object
              description: A pakjegemak key is still supported within this object, but it is not recommended to use. Please use `to_service_point` property to use service points.
            country:
              type: object
              description: Country of the recipient
              properties:
                iso_3:
                  type: string
                  example: NLD
                iso_2:
                  type: string
                  example: NL
                name:
                  type: string
                  example: Netherlands
            shipment:
              type: object
              description: Shipping method object for a parcel
              properties:
                id:
                  type: integer
                  example: 1
                  description: The unique identifier of the shipping method
                name:
                  type: string
                  example: PostNL Standard
                  description: The Sendcloud shipping method name
            order_number:
              type: string
              description: Order number of your order
              example: ORD12334
            shipment_uuid:
              type: string
              description: Unique identifier that we assign to your shipment within the Sendcloud system.
              example: 87e18823-016b-479b-b9e0-c5c0c4065452
            external_order_id:
              type: string
              description: Our system will ensure uniqueness of shipments with the combination of `external_order_id` and `external_shipment_id`
              example: AMZ23311
            external_shipment_id:
              type: string
              description: Our system will ensure uniqueness of shipments with the combination of `external_order_id` and `external_shipment_id`
              example: AMZ231231
    IntegrationConnectedWebhook:
      description: The webhook payload when an integration is added to Sendcloud
      type: object
      title: Webhook Integration Connected Object
      allOf:
      - $ref: '#/components/schemas/IntegrationWebhookBase'
      - type: object
        properties:
          action:
            type: string
            example: integration_connected
            enum:
            - integration_connected
    IntegrationUpdatedWebhook:
      description: The webhook payload when an integration is updated in Sendcloud
      type: object
      title: Webhook Integration Updated Object
      allOf:
      - $ref: '#/components/schemas/IntegrationWebhookBase'
      - type: object
        properties:
          action:
            type: string
            example: integration_updated
            enum:
            - integration_updated
    ReturnCreatedWebhook:
      title: Webhook Return Created Object
      type: object
      description: 'The webhook payload when a return is created. This is emitted when a return is created either via the API or the Return Portal.


        Creating a return manually via Return Form does NOT trigger the webhook.'
      properties:
        action:
          type: string
          description: Describes webhook action
          example: return_created
          enum:
          - return_created
        timestamp:
          type: number
          description: Unix timestamp
        data:
          type: object
          description: Information about the return
          required:
          - id
          properties:
            id:
              type: number
              description: The id of the return
              example: 42
            brand_id:
              type: integer
            order_number:
              type: string
            return_reason_id:
              type: integer
            return_address_id:
              type: integer
            paid_return:
              type: boolean
            delivery_choice:
              type: string
            refund_type:
              type: string
            items:
              type: array
              description: List of items for this return
              items:
                type: object
                properties:
                  item_id:
                    type: string
                  description:
                    type: string
                  quantity:
                    type: integer
                  sku:
                    type: string
                  hs_code:
                    type: string
                  return_reason_id:
                    type: integer
                required:
                - quantity
      required:
      - action
      - timestamp
      - data
  responses:
    '200':
      description: Return a 200 status to indicate that the data was processed successfully. The response body may contain the extended line item.
  securitySchemes:
    Sendcloud-Signature:
      name: Sendcloud-Signature
      type: apiKey
      in: header