BigCommerce Manage Webhooks (Bulk) API

openapi: 3.0.0
info:
  title: BigCommerce Abandoned Cart Emails Manage Webhooks (Bulk) API
  version: 3.0.0
  termsOfService: https://www.bigcommerce.com/terms
  description: Abandoned Cart Emails V3 API managing Handlebars-based emails.
  contact:
    name: BigCommerce
    url: https://www.bigcommerce.com
    email: support@bigcommerce.com
servers:
- url: https://api.bigcommerce.com/stores/{store_hash}/v3
  variables:
    store_hash:
      default: store_hash
      description: Permanent ID of the BigCommerce store.
  description: BigCommerce API Gateway
security:
- X-Auth-Token: []
tags:
- name: Manage Webhooks (Bulk)
paths:
  /hooks:
    post:
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/webhook_Full'
                  meta:
                    type: object
                    properties:
                      pagination:
                        $ref: '#/components/schemas/Pagination'
              examples:
                application/json:
                  value:
                    data:
                      id: 18048287
                      client_id: m9r6keqmo7h7f23btnpwernbez1kglkl
                      store_hash: sftg45fsd
                      created_at: 1561488106
                      updated_at: 1561488106
                      scope: store/order/*
                      destination: https://665b65a6.ngrok.io/webhooks
                      is_active: true
                      headers:
                        custom-key: developer-defined value
                    meta:
                      pagination:
                        count: 5
                        current_page: 1
                        links:
                          current: ?limit=100&page=1
                          next: ?limit=100&page=1
                          previous: ?limit=100&page=1
                        per_page: 100
                        total: 5
                        total_pages: 1
          links:
            getHook:
              operationId: getWebhook
              parameters:
                webhook_id: $response.body#/id
        '400':
          $ref: '#/components/responses/400_BadRequest'
        '401':
          $ref: '#/components/responses/401_Unauthorized'
        '422':
          $ref: '#/components/responses/422_UnprocessableEntity'
      summary: BigCommerce Create a Webhook
      description: Creates a webhook. Only one webhook at a time can be created. Custom headers can be added. Destination URL must be served on port 443 (custom ports are not currently supported).
      operationId: createWebhooks
      parameters:
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/Content-Type'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/webhook_Base'
      tags:
      - Manage Webhooks (Bulk)
    get:
      responses:
        '200':
          $ref: '#/components/responses/webhooks_Resp'
        '400':
          $ref: '#/components/responses/400_BadRequest'
        '401':
          $ref: '#/components/responses/401_Unauthorized'
      summary: BigCommerce Get Webhooks
      description: 'Returns a list of all webhooks on a store associated to the `client_id` used to authenticate the request.


        *Note: BigCommerce determines the `client_id` from the `access_token`.*'
      operationId: getWebhooks
      tags:
      - Manage Webhooks (Bulk)
      parameters:
      - $ref: '#/components/parameters/Accept'
      - $ref: '#/components/parameters/Content-Type'
      - $ref: '#/components/parameters/FilterPageParam'
      - $ref: '#/components/parameters/FilterLimitParam'
      - $ref: '#/components/parameters/IsActive'
      - $ref: '#/components/parameters/FilterByScope'
      - $ref: '#/components/parameters/FilterByDestination'
components:
  parameters:
    Accept:
      in: header
      name: Accept
      schema:
        type: string
        default: application/json
    FilterByScope:
      name: scope
      in: query
      description: 'Enables user to filter for webhooks by scope.

        '
      schema:
        type: string
    FilterPageParam:
      name: page
      in: query
      description: 'Page number.

        '
      required: false
      schema:
        type: integer
        example: 1
    FilterByDestination:
      name: destination
      in: query
      description: 'Enables user to filter for webhooks by destination.

        '
      schema:
        type: string
    FilterLimitParam:
      name: limit
      in: query
      description: 'Items count per page.

        '
      required: false
      schema:
        type: integer
    IsActive:
      name: is_active
      in: query
      description: 'Enables user to filter for webhooks that are active or not. A webhook subscription becomes deactivated after 90 days of inactivity.

        '
      schema:
        type: boolean
        example: true
    Content-Type:
      name: Content-Type
      in: header
      schema:
        type: string
        default: application/json
  schemas:
    webhook_Full:
      allOf:
      - $ref: '#/components/schemas/webhook_Base'
      - title: webhook_Full
        properties:
          id:
            type: integer
            description: ID of the webhook.
            example: 18048287
          client_id:
            type: string
            description: Client ID, unique to the store or app.
            example: m9r6keqmo7h7f23btnpwernbez1kglkl
          store_hash:
            type: string
            description: Permanent ID of the BigCommerce store.
            example: sftg45fsd
          created_at:
            type: integer
            example: 1561488106
            description: The time the webhook was created, represented in UNIX epoch time.
          updated_at:
            type: integer
            example: 1561488106
            description: The time the webhook was most recently updated, represented in UNIX epoch time.
    errorDetailed_Full:
      type: object
      title: errorDetailed_Full
      properties:
        status:
          description: 'The HTTP status code.

            '
          type: integer
        title:
          description: 'The error title describing the particular error.

            '
          type: string
        type:
          description: Typically a link to BigCommerce API Status codes
          type: string
        errors:
          type: object
      x-internal: false
    webhook_Base:
      type: object
      title: webhook_Base
      x-internal: false
      properties:
        scope:
          type: string
          example: store/order/*
          description: Event you subscribe to.
        destination:
          type: string
          example: https://665b65a6.ngrok.io/webhooks
          description: URL must be active, return a 200 response, and be served on port 443. Custom ports arenʼt currently supported.
        is_active:
          type: boolean
          example: true
          description: Boolean value that indicates whether the webhook is active or not. A webhook subscription becomes deactivated after 90 days of inactivity.
        events_history_enabled:
          type: boolean
          example: true
          description: Deprecated. Boolean value that identifies whether events are stored that could not be received.
          deprecated: true
        headers:
          type: object
          description: Headers used to validate that webhooks are active. You can pass in any number of custom headers to validate webhooks are being returned.
          nullable: true
          properties: {}
          additionalProperties:
            type: string
      required:
      - scope
      - destination
    Pagination:
      type: object
      description: 'Data about the response, including pagination and collection totals.

        '
      properties:
        total:
          type: integer
          description: Total number of returned items across all pages.
        count:
          type: integer
          description: Number of items on current page.
        per_page:
          type: integer
          description: Maximum number of items per page.
        current_page:
          type: integer
          description: Current page number.
        total_pages:
          type: integer
          description: Total number of pages.
        links:
          type: object
          properties:
            previous:
              type: string
              description: Link to the previous page returned in the response.
            current:
              type: string
              description: Link to the current page returned in the response.
            next:
              type: string
              description: Link to the next page returned in the response.
      x-internal: false
    error_Full:
      type: object
      title: error_Full
      properties:
        status:
          description: 'The HTTP status code.

            '
          type: integer
        title:
          description: 'The error title describing the particular error.

            '
          type: string
        type:
          description: This value is typically a link to BigCommerce API Status codes.
          type: string
      x-internal: false
  responses:
    webhooks_Resp:
      description: ''
      content:
        application/json:
          schema:
            description: ''
            type: object
            properties:
              data:
                type: array
                uniqueItems: true
                minItems: 1
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                    client_id:
                      type: string
                      minLength: 1
                    store_hash:
                      type: string
                      minLength: 1
                    scope:
                      type: string
                      minLength: 1
                    destination:
                      type: string
                      minLength: 1
                    headers:
                      type: object
                      properties: {}
                      nullable: true
                      additionalProperties:
                        type: string
                    is_active:
                      type: boolean
                    created_at:
                      type: integer
                      description: The time the webhook was created, represented in UNIX epoch time.
                    updated_at:
                      type: integer
                      description: The time the webhook was most recently updated, represented in UNIX epoch time.
              meta:
                type: object
                properties:
                  pagination:
                    $ref: '#/components/schemas/Pagination'
          examples: {}
    422_UnprocessableEntity:
      description: This occurs when missing or unacceptable data is passed for one or more fields. Please correct the values for the fields listed in the errors object.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorDetailed_Full'
          examples:
            response:
              value:
                status: 422
                title: JSON data is missing or invalid
                type: /api-docs/getting-started/api-status-codes
                errors:
                  destination: error.path.missing.
    400_BadRequest:
      description: Malformed request syntax. Typically need to fix the JSON request body to resend successfully.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error_Full'
          examples:
            response:
              value:
                status: 400
                title: Input is invalid.
                type: /api-docs/getting-started/api-status-codes
    401_Unauthorized:
      description: Unauthorized - the v3 Auth client ID or token in the request are not a valid combination for this store.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error_Full'
          examples:
            response:
              value:
                status: 401
                title: Unauthorized - the v3 Auth client ID or token in the request are not a valid combination for this store.
                type: /api-docs/getting-started/api-status-codes
  securitySchemes:
    X-Auth-Token:
      name: X-Auth-Token
      description: '### OAuth scopes


        | UI Name | Permission | Parameter |

        |:--|:--|:-|

        | Information & Settings  | read-only  | `store_v2_information_read_only`|

        | Information & Settings  | modify     | `store_v2_information`          |


        ### Authentication header


        | Header | Argument | Description |

        |:-|:|:|

        | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). |


        ### Further reading


        For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests).


        For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes).


        For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes).'
      type: apiKey
      in: header