Bootic Webhooks API

openapi: 3.2.0
info:
  title: Bolder API v2 Webhooks API
  version: '2.0'
  description: '## Getting Started


    The Bolder API provides programmatic access to your Bolder Shop data through a

    hypermedia-driven REST interface.'
  contact:
    name: Bolder API Support
    url: https://www.onbolder.com
servers:
- url: https://api.onbolder.com/v2
  description: Production
security:
- bearerAuth: []
tags:
- name: Webhooks
  description: 'Event webhooks. Subscribe to events such as `orders.created`, `products.updated`, etc.

    Inactive subscriptions can be reactivated and their delivery history inspected.'
paths:
  /webhooks:
    get:
      tags:
      - Webhooks
      summary: List webhooks
      operationId: listWebhooksFlattened
      parameters:
      - name: shop_id
        in: query
        schema:
          type: integer
        description: Filter by shop ID
      - name: seller_id
        in: query
        schema:
          type: integer
        description: Filter by seller ID
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      - name: per_page
        in: query
        schema:
          type: integer
          default: 30
      - name: status
        in: query
        schema:
          type: string
        description: Filter by status (active, failed_activation, failed, disabled)
      x-codeSamples:
      - lang: Shell
        label: cURL
        source: "# List all webhooks for account\ncurl -s -H \"Authorization: Bearer $BOLDER_TOKEN\" \\\n  \"https://api.onbolder.com/v2/webhooks\"\n\n# Filter by shop\ncurl -s -H \"Authorization: Bearer $BOLDER_TOKEN\" \\\n  \"https://api.onbolder.com/v2/webhooks?shop_id=1\"\n"
      description: 'Returns webhooks across the account.

        Optionally filter by `shop_id` or `seller_id` query parameter.


        ## Delivery payload guarantees


        Every order-related event payload (`orders.created`, `orders.updated`,

        `orders.updated.*`) is built from the same serializer and always includes

        both `id` (numeric order id) and `code` (the order''s public-facing

        reference/permalink) — neither is ever omitted.


        ## Retries and automatic disabling


        Two independent counters are involved — don''t confuse them:


        - **Per-event retries (up to 10, over ~24h)**: each individual event

        delivery (e.g. one order''s `orders.updated`) is retried by the

        delivery worker up to 10 times with growing backoff, spread across

        roughly a day (a few minutes after the 1st failure, up to ~24h

        after it by the 10th and final attempt) — this gives a

        temporarily-down endpoint a full day to recover before this

        specific event delivery is given up on.

        - **Subscription-wide `error_count` (disables at 100)**: every

        failed attempt across *all* events (including each of the 10

        per-event retries above) increments `error_count` on the

        subscription. Reaching 100 sets `status` to `failed` and stops all

        further delivery — in practice that means roughly 10 different

        order events each exhausting their full retry chain with no

        successful delivery in between, since **any single successful

        delivery resets `error_count` to 0**. There''s no fixed time bound

        on this: it depends on how many order events fire while your

        endpoint is down.


        Delivery outcomes are tracked on the subscription independent of the

        worker retries:


        - A `410 Gone` response from your endpoint immediately sets the

        subscription''s `status` to `disabled` — no further attempts are made,

        regardless of `error_count`.

        - Any other non-2xx response (or timeout) increments `error_count`.

        Timeouts and a handful of transient upstream errors (502/512/523) don''t

        count toward the disable threshold; other non-2xx responses do.

        - A `failed` (or `disabled`) subscription can be re-enabled at any time via

        `PUT /webhooks/{id}/reactivate`, which resets the error count.'
      responses:
        '200':
          description: Webhooks list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookList'
    post:
      tags:
      - Webhooks
      summary: Create a webhook
      description: '`shop_id` is required when creating via this flat endpoint. Alternatively, use `POST /sellers/{seller_id}/webhooks`.'
      operationId: createWebhookFlattened
      parameters:
      - name: shop_id
        in: query
        required: true
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookInput'
            example:
              topic: orders.created
              url: https://myapp.com/webhook
      responses:
        '201':
          description: Webhook created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '403':
          description: Token lacks the scope required to subscribe to this topic
  /webhooks/{id}:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: integer
    get:
      tags:
      - Webhooks
      summary: Get a webhook
      operationId: getWebhookFlattened
      responses:
        '200':
          description: Webhook details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
    delete:
      tags:
      - Webhooks
      summary: Delete a webhook
      operationId: deleteWebhookFlattened
      responses:
        '204':
          description: Webhook deleted
  /webhooks/{id}/reactivate:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: integer
    put:
      tags:
      - Webhooks
      summary: Reactivate a failed webhook
      operationId: reactivateWebhookFlattened
      responses:
        '200':
          description: Webhook reactivated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
  /webhooks/{id}/history:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: integer
    get:
      tags:
      - Webhooks
      summary: Get webhook delivery history
      operationId: webhookHistoryFlattened
      responses:
        '200':
          description: Delivery history
  /sellers/{seller_id}/webhooks:
    parameters:
    - name: seller_id
      in: path
      required: true
      schema:
        type: integer
    get:
      tags:
      - Webhooks
      summary: List webhooks for a seller
      description: Seller-nested equivalent of `GET /webhooks?seller_id=X`.
      operationId: listSellerWebhooks
      x-codeSamples:
      - lang: Shell
        label: cURL
        source: "curl -s -H \"Authorization: Bearer $BOLDER_TOKEN\" \\\n  \"https://api.onbolder.com/v2/sellers/5/webhooks\"\n"
      responses:
        '200':
          description: Webhooks list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookList'
    post:
      tags:
      - Webhooks
      summary: Create a webhook for a seller
      operationId: createSellerWebhook
      x-codeSamples:
      - lang: Shell
        label: cURL
        source: "curl -s -X POST \\\n  -H \"Authorization: Bearer $BOLDER_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"topic\":\"orders.created\",\"url\":\"https://myapp.com/webhook\"}' \\\n  \"https://api.onbolder.com/v2/sellers/5/webhooks\"\n"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookInput'
            example:
              topic: orders.created
              url: https://myapp.com/webhook
      responses:
        '201':
          description: Webhook created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
              example:
                id: 101
                channel_id: 5
                topic: orders.created
                url: https://myapp.com/webhook
                status: pending
                notify_origin: false
                _links:
                  self:
                    href: https://api.onbolder.com/v2/webhooks/101
        '403':
          description: Token lacks the scope required to subscribe to this topic
components:
  schemas:
    WebhookInput:
      type: object
      required:
      - topic
      - url
      properties:
        topic:
          type: string
          example: orders.created
          description: 'Supported topics: `orders.created`, `orders.updated`,

            `orders.updated.closed`, `orders.updated.shipped`,

            `contacts.created`, `contacts.updated`, `products.created`,

            `products.updated`, `products.deleted`

            '
        url:
          type: string
          example: https://myapp.com/webhook
        notify_origin:
          type: boolean
          default: false
          description: If false, does not notify the request-originating host
        auth:
          type: object
          properties:
            type:
              type: string
              enum:
              - none
              - basic
              default: none
            username:
              type: string
            password:
              type: string
    Pagination:
      type: object
      properties:
        total_items:
          type: integer
          example: 42
        per_page:
          type: integer
          example: 20
        page:
          type: integer
          example: 1
    Webhook:
      type: object
      properties:
        _links:
          $ref: '#/components/schemas/HalLinks'
        id:
          type: integer
        channel_id:
          type: integer
        topic:
          type: string
          example: orders.created
        url:
          type: string
          example: https://myapp.com/events
        status:
          type: string
          enum:
          - active
          - failed_activation
          - failed
          - disabled
          description: '`active` — receiving deliveries normally.

            `failed_activation` — the initial activation handshake failed.

            `failed` — disabled automatically after 100 consecutive non-2xx delivery

            responses (see `error_count`); can be re-enabled via

            `PUT /webhooks/{id}/reactivate`.

            `disabled` — the target URL returned `410 Gone`; disabled immediately,

            with no retry threshold. Also reactivatable via the same endpoint.

            '
        auth:
          type: object
        notify_origin:
          type: boolean
        app_id:
          type: integer
        error_count:
          type: integer
        last_error:
          type: string
        last_error_on:
          type: string
          format: date-time
        created_on:
          type: string
          format: date-time
        updated_on:
          type: string
          format: date-time
    WebhookList:
      allOf:
      - $ref: '#/components/schemas/Pagination'
      - type: object
        properties:
          _links:
            $ref: '#/components/schemas/HalLinks'
          _class:
            type: array
            items:
              type: string
            example:
            - results
            - hubSubscriptions
          _embedded:
            type: object
            properties:
              subscriptions:
                type: array
                items:
                  $ref: '#/components/schemas/Webhook'
    HalLinks:
      type: object
      additionalProperties:
        oneOf:
        - $ref: '#/components/schemas/HalLink'
        - type: array
          items:
            $ref: '#/components/schemas/HalLink'
    HalLink:
      type: object
      required:
      - href
      properties:
        href:
          type: string
        templated:
          type: boolean
        method:
          type: string
          enum:
          - get
          - post
          - put
          - patch
          - delete
        title:
          type: string
        type:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.onbolder.com/oauth/token
          scopes:
            products.read: View products, variants and collections
            products.write: Create and update products
            orders.read: View orders
            orders.write: Create and update orders
            customers.read: View customer profiles
            customers.write: Update customer profiles
            shops.read: View shop configuration
            shops.write: Update shop configuration
            hub.read: View content (posts, pages)
            hub.write: Create and update content
            store.read: View themes and assets
            store.write: Manage themes and assets
            sellers.read: View seller information
            batches.read: View batch job status
            batches.write: Create and run batch jobs
        authorizationCode:
          authorizationUrl: https://auth.onbolder.com/oauth/authorize
          tokenUrl: https://auth.onbolder.com/oauth/token
          scopes:
            products.read: View products, variants and collections
            products.write: Create and update products
            orders.read: View orders
            orders.write: Create and update orders
            customers.read: View customer profiles
            customers.write: Update customer profiles
            shops.read: View shop configuration
            shops.write: Update shop configuration
            hub.read: View content (posts, pages)
            hub.write: Create and update content
            store.read: View themes and assets
            store.write: Manage themes and assets
            sellers.read: View seller information
            batches.read: View batch job status
            batches.write: Create and run batch jobs