# Create Bolt Webhook

> 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.

Source: https://help.boltapp.com/api-reference/endpoints/webhooks/createwebhook

`POST /v1/webhooks`

## OpenAPI definition

This endpoint as it appears in the OpenAPI document, with every schema it references included.

```json
{
  "openapi": "3.2.0",
  "info": {
    "version": "1.0.1",
    "title": "Bolt API Reference",
    "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"
      ]
    }
  ],
  "paths": {
    "/v1/webhooks": {
      "post": {
        "description": "Create a new webhook to receive notifications from Bolt about various events, such as transaction status. Webhooks must have unique configuration.\n\n**Transaction & account events**:\n* `pending` - The payment pre-authorization was successful, and the transaction is now pending fraud review.\n* `failed_payment` - The payment failed pre-authorization.\n* `payment` - An automatic capture transaction passed authorization and fraud review, and the system captured the funds.\n* `auth` - A manual capture transaction passed authorization and fraud review, and you can begin the capture process.\n* `rejected_irreversible` - The transaction failed fraud review, with no appeal option available.\n* `rejected_reversible` - The transaction was flagged during fraud review; a re-review can be requested.\n* `capture` - A manual capture was successful.\n* `credit` - The system successfully processed a refund or credit.\n* `void` - The system successfully voided the transaction.\n* `newsletter_subscription` - The customer subscribed to the merchant's newsletter.\n* `risk_insights` - Information about the transaction's risk is available from the fraud review.\n* `credit_card_deleted` - A customer removed a saved credit card from their account.\n\n**Subscription events**:\n* `subscription_created` - A subscription was created from a successful initial transaction.\n* `subscription_renewed` - A recurring subscription order was placed successfully and the next order was scheduled.\n* `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.\n* `subscription_payment_failed` - A scheduled subscription order's payment attempt failed.\n* `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).\n* `subscription_unpaused` - A paused subscription was resumed, by the merchant or by the shopper.\n* `subscription_ended` - A subscription was permanently ended after its dunning retry schedule was exhausted. Sent alongside `subscription_canceled` for this case.\n",
        "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"
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "event_group_create_webhook": {
        "allOf": [
          {
            "$ref": "#/components/schemas/base_create_webhook"
          },
          {
            "type": "object"
          }
        ],
        "properties": {
          "event_group": {
            "$ref": "#/components/schemas/webhook_event_group"
          }
        }
      },
      "base_create_webhook": {
        "properties": {
          "division_id": {
            "description": "The unique ID associated with the specific merchant division.",
            "type": "string",
            "examples": [
              "3X9aPQ67-YrB"
            ]
          },
          "url": {
            "$ref": "#/components/schemas/url"
          }
        },
        "required": [
          "division_id",
          "url"
        ],
        "type": "object"
      },
      "url": {
        "description": "The full URL to receive webhook notifications.",
        "type": "string",
        "examples": [
          "https://eva-nerv.shop.com/path/to/hook"
        ]
      },
      "webhook_event_group": {
        "description": "Subscribe to a group of events.\n`all`: subscribe to all existing and future event types\n",
        "enum": [
          "all",
          "null"
        ],
        "type": [
          "string",
          "null"
        ]
      },
      "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.\n",
            "items": {
              "$ref": "#/components/schemas/webhooks_type"
            },
            "type": "array"
          }
        }
      },
      "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.\n\nSubscription events:\n* `subscription_created` - A subscription was created from a successful initial transaction.\n* `subscription_renewed` - A recurring subscription order was placed successfully and the next order was scheduled.\n* `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.\n* `subscription_payment_failed` - A scheduled subscription order's payment attempt failed.\n* `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).\n* `subscription_unpaused` - A paused subscription was resumed, by the merchant or by the shopper.\n* `subscription_ended` - A subscription was permanently ended after its dunning retry schedule was exhausted. Sent alongside `subscription_canceled` for this case.\n",
        "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"
        ],
        "type": "string",
        "examples": [
          "pending"
        ]
      },
      "webhook_id": {
        "description": "A unique webhook ID. Reference this value to modify or delete the webhook subscription. operations as well.",
        "type": "string",
        "examples": [
          "wh_za7VbYcSQU2zRgGQXQAm-g"
        ]
      },
      "errors_bolt_api_response": {
        "properties": {
          "errors": {
            "$ref": "#/components/schemas/errors_bolt_api"
          },
          "result": {
            "$ref": "#/components/schemas/request_result"
          }
        },
        "type": "object"
      },
      "errors_bolt_api": {
        "items": {
          "$ref": "#/components/schemas/error_bolt_api"
        },
        "type": "array"
      },
      "error_bolt_api": {
        "properties": {
          "code": {
            "$ref": "#/components/schemas/code"
          },
          "message": {
            "$ref": "#/components/schemas/message"
          }
        },
        "type": "object",
        "description": "Error object containing custom error information"
      },
      "code": {
        "description": "Custom-defined Bolt error code. This can be used to programmatically react to specific errors.",
        "format": "int64",
        "type": "integer",
        "examples": [
          2001005
        ]
      },
      "message": {
        "description": "Human-readable description of the error for developers. Should not be shown to users and is not localized.",
        "type": "string",
        "examples": [
          "The input is missing a required parameter."
        ]
      },
      "request_result": {
        "description": "Custom-defined Bolt result object.",
        "properties": {
          "success": {
            "$ref": "#/components/schemas/request_failed"
          }
        },
        "type": "object"
      },
      "request_failed": {
        "type": "boolean",
        "description": "Indicates that the request failed. This value is always false.",
        "examples": [
          false
        ]
      }
    },
    "securitySchemes": {
      "OAuth": {
        "description": "Bolt utilizes the OAuth flow that developers can use to attain access to Bolt Account data via APIs.\nFor all APIs that require authorization, please provide your `access_token` returned from `/v1/oauth/token` via the basic auth bearer header `Authorization: bearer ${TOKEN}`.\n[Read more about the OAuth token endpoint.](/api-bolt/#tag/OAuth)\n",
        "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"
      }
    }
  }
}
```