---
title: "Create Bolt Webhook"
method: POST
path: "/v1/webhooks"
tags: ["Webhooks"]
---

# Create Bolt Webhook

`POST /v1/webhooks`

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.

## Request body

- union
  - EventGroupCreateWebhook
    - `division_id` string, required — The unique ID associated with the specific merchant division.
    - `url` string, required — The full URL to receive webhook notifications.
    - `event_group` 'all' | 'null', nullable — Subscribe to a group of events. `all`: subscribe to all existing and future event types
  - EventsArrayCreateWebhook
    - `division_id` string, required — The unique ID associated with the specific merchant division.
    - `url` string, required — The full URL to receive webhook notifications.
    - `events` WebhooksType[] — If `webhook_event_group` is null, pick a list of notification events to subscribe to.

## Response `200`

Success

- object
  - `webhook_id` string, required — A unique webhook ID. Reference this value to modify or delete the webhook subscription. operations as well.

## Other responses

- `400` — BAD REQUEST. Request is malformed or invalid values are detected.
- `403` — FORBIDDEN. Not authorized to create a webhook for this entity.
- `422` — 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.

## Changes

- **2026-07-31** `1f62c40558c6` — 7 info
  - added the new `subscription_canceled` enum value to the request property `oneOf[#/components/schemas/events_array_create_webhook]/events/items/`
  - added the new `subscription_created` enum value to the request property `oneOf[#/components/schemas/events_array_create_webhook]/events/items/`
  - added the new `subscription_ended` enum value to the request property `oneOf[#/components/schemas/events_array_create_webhook]/events/items/`
  - added the new `subscription_paused` enum value to the request property `oneOf[#/components/schemas/events_array_create_webhook]/events/items/`
  - …3 more

[Change history](https://skmtc.dev/bolt/apis/bolt-api-reference/changes/v1/webhooks/post.md)

---

[API](https://skmtc.dev/bolt/apis/bolt-api-reference.md) · [All operations](https://skmtc.dev/bolt/apis/bolt-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/bolt/bolt-api-reference/revisions/1f62c40558c6/schema)