openapi: 3.2.0
info:
  version: 1.0.1
  title: Bolt API Reference Webhooks API
  description: "Postman Collection:\n\n[![](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/9136127-55d2bde1-a248-473f-95b5-64cfd02fb445?action=collection%2Ffork&collection-url=entityId%3D9136127-55d2bde1-a248-473f-95b5-64cfd02fb445%26entityType%3Dcollection%26workspaceId%3D78beee89-4238-4c5f-bd1f-7e98978744b4#?env%5BBolt%20Sandbox%20Environment%5D=W3sia2V5IjoiYXBpX2Jhc2VfdXJsIiwidmFsdWUiOiJodHRwczovL2FwaS1zYW5kYm94LmJvbHQuY29tIiwidHlwZSI6ImRlZmF1bHQiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6InRrX2Jhc2UiLCJ2YWx1ZSI6Imh0dHBzOi8vc2FuZGJveC5ib2x0dGsuY29tIiwidHlwZSI6ImRlZmF1bHQiLCJlbmFibGVkIjp0cnVlfSx7ImtleSI6ImFwaV9rZXkiLCJ2YWx1ZSI6IjxyZXBsYWNlIHdpdGggeW91ciBCb2x0IFNhbmRib3ggQVBJIGtleT4iLCJ0eXBlIjoic2VjcmV0IiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJwdWJsaXNoYWJsZV9rZXkiLCJ2YWx1ZSI6IjxyZXBsYWNlIHdpdGggeW91ciBCb2x0IFNhbmRib3ggcHVibGlzaGFibGUga2V5PiIsInR5cGUiOiJkZWZhdWx0IiwiZW5hYmxlZCI6dHJ1ZX0seyJrZXkiOiJkaXZpc2lvbl9pZCIsInZhbHVlIjoiPHJlcGxhY2Ugd2l0aCB5b3VyIEJvbHQgU2FuZGJveCBwdWJsaWMgZGl2aXNpb24gSUQ+IiwidHlwZSI6ImRlZmF1bHQiLCJlbmFibGVkIjp0cnVlfV0=)\n\n## About\n A comprehensive Bolt API reference for interacting with Transactions, Orders, Product Catalog, Configuration, Testing, and much more.\n\n Note: You must also reference the [Merchant Callback API](/api-merchant) when building a managed checkout custom cart integration\n"
servers:
- url: https://api.boltapp.com
  description: The Production URL (Live Data).
- url: https://api-sandbox.boltapp.com
  description: The Sandbox URL (Test Data).
- url: https://api-staging.boltapp.com
  description: The Staging URL (Staged Data).
security:
- X-API-Key: []
- OAuth:
  - bolt.account.manage
  - bolt.account.view
tags:
- name: Webhooks
  description: 'Set up webhooks to notify your backend of events within Bolt. These webhooks can communicate with your OMS or other systems to keep them up to date with Bolt. See our related guide on [Webhooks](https://help.boltapp.com/get-started/during-checkout/webhooks/).

    '
paths:
  /v1/webhooks:
    get:
      description: Find webhook configurations belonging to a merchant division. Results are limited to only show webhooks authorized by the X-API-Key.
      operationId: queryWebhooks
      parameters:
      - $ref: '#/components/parameters/division_id'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  webhooks:
                    items:
                      $ref: '#/components/schemas/webhook'
                    type: array
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors_bolt_api_response'
          description: BAD REQUEST. Request is malformed or invalid values are detected.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors_bolt_api_response'
          description: FORBIDDEN. Not authorized to query webhook for this entity.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors_bolt_api_response'
          description: NOT FOUND. Unable to find webhook.
      security:
      - X-API-Key: []
      summary: Query Webhooks
      tags:
      - Webhooks
    post:
      description: 'Create a new webhook to receive notifications from Bolt about various events, such as transaction status. Webhooks must have unique configuration.


        **Transaction & account events**:

        * `pending` - The payment pre-authorization was successful, and the transaction is now pending fraud review.

        * `failed_payment` - The payment failed pre-authorization.

        * `payment` - An automatic capture transaction passed authorization and fraud review, and the system captured the funds.

        * `auth` - A manual capture transaction passed authorization and fraud review, and you can begin the capture process.

        * `rejected_irreversible` - The transaction failed fraud review, with no appeal option available.

        * `rejected_reversible` - The transaction was flagged during fraud review; a re-review can be requested.

        * `capture` - A manual capture was successful.

        * `credit` - The system successfully processed a refund or credit.

        * `void` - The system successfully voided the transaction.

        * `newsletter_subscription` - The customer subscribed to the merchant''s newsletter.

        * `risk_insights` - Information about the transaction''s risk is available from the fraud review.

        * `credit_card_deleted` - A customer removed a saved credit card from their account.


        **Subscription events**:

        * `subscription_created` - A subscription was created from a successful initial transaction.

        * `subscription_renewed` - A recurring subscription order was placed successfully and the next order was scheduled.

        * `subscription_canceled` - A subscription was canceled, by the merchant, by the shopper, or automatically (e.g. once its dunning retry schedule is exhausted). Also sent alongside `subscription_ended` when the subscription''s configured final dunning action is cancellation.

        * `subscription_payment_failed` - A scheduled subscription order''s payment attempt failed.

        * `subscription_paused` - A subscription was paused, by the merchant, by the shopper, or automatically once its dunning retry schedule is exhausted (when the configured final dunning action is pausing).

        * `subscription_unpaused` - A paused subscription was resumed, by the merchant or by the shopper.

        * `subscription_ended` - A subscription was permanently ended after its dunning retry schedule was exhausted. Sent alongside `subscription_canceled` for this case.

        '
      operationId: createWebhook
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/event_group_create_webhook'
              - $ref: '#/components/schemas/events_array_create_webhook'
        description: Webhook that receives notifications.
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  webhook_id:
                    $ref: '#/components/schemas/webhook_id'
                required:
                - webhook_id
                type: object
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors_bolt_api_response'
          description: BAD REQUEST. Request is malformed or invalid values are detected.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors_bolt_api_response'
          description: FORBIDDEN. Not authorized to create a webhook for this entity.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors_bolt_api_response'
          description: UNPROCESSABLE ENTITY. Not allowed to receive duplicate notifications. This is to safeguard a webhook listener from receiving duplicate events. Use GET /v1/webhooks and DELETE /v1/webhooks to check for and delete duplicate webhooks.
      security:
      - X-API-Key: []
      summary: Create Bolt Webhook
      tags:
      - Webhooks
  /v1/webhooks/{webhook_id}:
    delete:
      description: Delete a Bolt webhook. Provide an authorized X-API-Key to perform this action.
      operationId: deleteWebhook
      parameters:
      - description: Webhook ID
        in: path
        name: webhook_id
        required: true
        schema:
          $ref: '#/components/schemas/webhook_id'
      responses:
        '200':
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors_bolt_api_response'
          description: BAD REQUEST. Request is malformed or invalid values are detected.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors_bolt_api_response'
          description: FORBIDDEN. Not authorized to perform the operation on this resource.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors_bolt_api_response'
          description: NOT FOUND. Unable to find webhook.
      security:
      - X-API-Key: []
      summary: Delete a Bolt Webhook
      tags:
      - Webhooks
    get:
      description: Get Webhook information by its Webhook ID. Results only include webhooks authorized by the X-API-Key.
      operationId: getWebhook
      parameters:
      - description: Webhook ID
        in: path
        name: webhook_id
        required: true
        schema:
          $ref: '#/components/schemas/webhook_id'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/webhook'
          description: Success
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors_bolt_api_response'
          description: BAD REQUEST. Request is malformed or invalid values are detected.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors_bolt_api_response'
          description: FORBIDDEN. Not authorized to perform the operation on this resource.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/errors_bolt_api_response'
          description: NOT FOUND. Unable to find webhook.
      security:
      - X-API-Key: []
      summary: Get Webhook
      tags:
      - Webhooks
components:
  schemas:
    error_bolt_api:
      properties:
        code:
          $ref: '#/components/schemas/code'
        message:
          $ref: '#/components/schemas/message'
      type: object
      description: Error object containing custom error information
    message:
      description: Human-readable description of the error for developers. Should not be shown to users and is not localized.
      example: The input is missing a required parameter.
      type: string
    url:
      description: The full URL to receive webhook notifications.
      example: https://eva-nerv.shop.com/path/to/hook
      type: string
    request_result:
      description: Custom-defined Bolt result object.
      properties:
        success:
          $ref: '#/components/schemas/request_failed'
      type: object
    events_array_create_webhook:
      allOf:
      - $ref: '#/components/schemas/base_create_webhook'
      - type: object
      properties:
        events:
          description: 'If `webhook_event_group` is null, pick a list of notification events to subscribe to.

            '
          items:
            $ref: '#/components/schemas/webhooks_type'
          type: array
    errors_bolt_api:
      items:
        $ref: '#/components/schemas/error_bolt_api'
      type: array
    webhook:
      properties:
        created_at:
          description: Webhook creation time in epoch timestamp milliseconds.
          example: 1485997169003
          type: integer
        event_group:
          $ref: '#/components/schemas/webhook_event_group'
        events:
          description: 'All events the webhook is subscribed to. Null when `event_group` = `all`.

            '
          items:
            $ref: '#/components/schemas/webhooks_type'
          type:
          - array
          - 'null'
        url:
          $ref: '#/components/schemas/url'
        webhook_id:
          $ref: '#/components/schemas/webhook_id'
      required:
      - webhook_id
      - created_at
      - url
      type: object
    base_create_webhook:
      properties:
        division_id:
          description: The unique ID associated with the specific merchant division.
          example: 3X9aPQ67-YrB
          type: string
        url:
          $ref: '#/components/schemas/url'
      required:
      - division_id
      - url
      type: object
    webhook_id:
      description: A unique webhook ID. Reference this value to modify or delete the webhook subscription. operations as well.
      example: wh_za7VbYcSQU2zRgGQXQAm-g
      type: string
    webhook_event_group:
      description: 'Subscribe to a group of events.

        `all`: subscribe to all existing and future event types

        '
      enum:
      - all
      - 'null'
      type:
      - string
      - 'null'
    errors_bolt_api_response:
      properties:
        errors:
          $ref: '#/components/schemas/errors_bolt_api'
        result:
          $ref: '#/components/schemas/request_result'
      type: object
    code:
      description: Custom-defined Bolt error code. This can be used to programmatically react to specific errors.
      example: 2001005
      format: int64
      type: integer
    event_group_create_webhook:
      allOf:
      - $ref: '#/components/schemas/base_create_webhook'
      - type: object
      properties:
        event_group:
          $ref: '#/components/schemas/webhook_event_group'
    webhooks_type:
      description: '[Webhook events](https://help.boltapp.com/developers/guides/webhooks/#transaction-hook-types) that trigger a notification to the URL.  **Note**:`newsletter_subscription` is only for merchant use cases.


        Subscription events:

        * `subscription_created` - A subscription was created from a successful initial transaction.

        * `subscription_renewed` - A recurring subscription order was placed successfully and the next order was scheduled.

        * `subscription_canceled` - A subscription was canceled, by the merchant, by the shopper, or automatically (e.g. once its dunning retry schedule is exhausted). Also sent alongside `subscription_ended` when the subscription''s configured final dunning action is cancellation.

        * `subscription_payment_failed` - A scheduled subscription order''s payment attempt failed.

        * `subscription_paused` - A subscription was paused, by the merchant, by the shopper, or automatically once its dunning retry schedule is exhausted (when the configured final dunning action is pausing).

        * `subscription_unpaused` - A paused subscription was resumed, by the merchant or by the shopper.

        * `subscription_ended` - A subscription was permanently ended after its dunning retry schedule was exhausted. Sent alongside `subscription_canceled` for this case.

        '
      enum:
      - payment
      - credit
      - capture
      - void
      - auth
      - pending
      - rejected_irreversible
      - rejected_reversible
      - failed_payment
      - newsletter_subscription
      - risk_insights
      - credit_card_deleted
      - subscription_created
      - subscription_renewed
      - subscription_canceled
      - subscription_payment_failed
      - subscription_paused
      - subscription_unpaused
      - subscription_ended
      example: pending
      type: string
    request_failed:
      example: false
      type: boolean
      description: Indicates that the request failed. This value is always false.
  parameters:
    division_id:
      description: The unique ID associated to the merchant's Bolt Account division; Merchants can have different divisions to suit multiple use cases (storefronts, pay-by-link, phone order processing). You can view and switch between these divisions from the Bolt Merchant Dashboard.
      in: query
      name: division_id
      required: true
      schema:
        type: string
  securitySchemes:
    OAuth:
      description: 'Bolt utilizes the OAuth flow that developers can use to attain access to Bolt Account data via APIs.

        For all APIs that require authorization, please provide your `access_token` returned from `/v1/oauth/token` via the basic auth bearer header `Authorization: bearer ${TOKEN}`.

        [Read more about the OAuth token endpoint.](/api-bolt/#tag/OAuth)

        '
      flows:
        authorizationCode:
          authorizationUrl: https://api.boltapp.com/v1/oauth/authorize
          refreshUrl: https://api.boltapp.com/v1/oauth/token
          scopes:
            bolt.account.manage: This scope grants permissions to perform read/edit/delete actions on Bolt Account data
            bolt.account.view: This scope grants permissions to perform read only actions on Bolt Account data
            openid: This scope grants permissions that enable Bolt SSO by granting an id token JWT that stores account data. Not used in v1/account endpoints
          tokenUrl: https://api.boltapp.com/v1/oauth/token
      type: oauth2
    X-API-Key:
      description: Admins and Developers can obtain their Bolt API key from the Bolt Merchant Dashboard.
      in: header
      name: X-API-Key
      type: apiKey