> ## Documentation Index > Fetch the complete documentation index at: https://developers.circle.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a webhook subscription > Create a webhook subscription by configuring an endpoint to receive notifications. ## OpenAPI ````yaml openapi/accounts.yaml post /v2/notifications/subscriptions openapi: 3.1.0 info: version: 1.0.0 title: Accounts (Stablecoin) API description: > Circle's Accounts API provides endpoints for managing stablecoin accounts -- including transfers, withdrawals, deposits, wire and ACH bank accounts, and blockchain addresses. An **Account** is a general representation of a ledger or custody object that holds balances. It can be a business account, a stablecoin account ledger for an end user, an extra sub-ledger, or any future custody solution. license: name: Circle License url: https://circle.com/terms servers: - url: https://api-sandbox.circle.com - url: https://api.circle.com security: [] tags: - name: Accounts description: Manage accounts. - name: Account Groups description: Manage custody account groups and their memberships. - name: Limits description: View effective account limits and current usage. - name: Transfers description: Manage account transfers. - name: Transactions description: | Get a unified, customer-friendly view of account transaction activity. - name: Wires description: Manage account bank accounts for wire transfers. - name: Deposits description: Get information on account bank deposits. - name: Withdrawals description: Manage account bank withdrawals (fiat offramp). - name: ACH description: Manage account bank accounts for ACH transfers. - name: Deposit Addresses description: Manage account deposit addresses. - name: Recipient Addresses description: Manage account recipient addresses used for transfers. - name: Webhook Subscriptions description: Manage subscriptions to Digital Asset Accounts webhook notifications. paths: /v2/notifications/subscriptions: post: tags: - Webhook Subscriptions summary: Create a webhook subscription description: > Create a webhook subscription by configuring an endpoint to receive notifications. operationId: createSubscription parameters: - $ref: '#/components/parameters/XRequestId' requestBody: $ref: '#/components/requestBodies/CreateSubscriptionRequest' responses: '200': content: application/json: schema: $ref: '#/components/schemas/CreateSubscriptionResponse' description: Successfully created webhook subscription. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/NotAuthorized' '500': $ref: '#/components/responses/InternalServerError' security: - bearerAuth: [] components: parameters: XRequestId: name: X-Request-Id description: >- Developer-provided parameter used to identify this request. Useful when communicating with Circle Support. in: header schema: $ref: '#/components/schemas/XRequestId' requestBodies: CreateSubscriptionRequest: content: application/json: schema: description: Required parameters to create a new subscription. type: object required: - endpoint properties: endpoint: type: string description: > URL of the endpoint to subscribe to notifications. Must be publicly accessible, use HTTPS, and respond with a 2XX status to a POST request. example: https://example.org/handler/for/notifications notificationTypes: type: array description: > The notification types to subscribe to. If not provided, the webhook is unrestricted and a notification is sent for every notification type. If the wildcard (`*`) is provided, the webhook is also unrestricted. If a set of notification types is provided, the webhook is restricted to those types. Each category has a wildcard — for example, `mint.*` restricts to every mint event. items: $ref: '#/components/schemas/NotificationType' example: - '*' required: true description: Schema for the request payload to create a new subscription. schemas: CreateSubscriptionResponse: title: SubscriptionResponse type: object properties: data: $ref: '#/components/schemas/Subscription' XRequestId: type: string format: uuid example: 2adba88e-9d63-44bc-b975-9b6ae3440dde NotificationType: type: string description: | The type of notification that can be subscribed to. Supports wildcard patterns — for example, `mint.*` subscribes to every mint event. The `*` wildcard subscribes to every Digital Asset Accounts notification type. enum: - '*' - custody.* - custody.transfer - mint.* - mint.deposits - mint.payout - mint.wire - mint.addressBookRecipients - bankAccounts.* - bankAccounts.created - bankAccounts.updated - bankAccounts.denied example: custody.transfer Subscription: type: object title: Subscription description: Contains information about a webhook notification subscription. required: - id - name - endpoint - enabled - createDate - updateDate properties: id: $ref: '#/components/schemas/Id' name: type: string description: Name of the webhook notification subscription. example: Digital Asset Accounts Webhook endpoint: type: string description: >- URL of the endpoint subscribing to notifications. Must be enabled to receive notifications. example: https://example.org/handler/for/notifications enabled: type: boolean description: >- Whether the subscription is enabled. `true` indicates the subscription is enabled. example: true createDate: type: string format: date-time description: Date and time the subscription was created. example: '2026-08-25T19:17:02.429Z' updateDate: type: string format: date-time description: Date and time the subscription was last updated. example: '2026-08-25T19:17:02.429Z' notificationTypes: type: array description: The notification types on which a notification will be sent. items: $ref: '#/components/schemas/NotificationType' example: - '*' restricted: type: boolean description: > Whether the webhook is restricted to specific notification types. An unrestricted webhook notifies on all notification types. A restricted webhook only notifies on the notification types in the `notificationTypes` field. example: false Error: type: object required: - code - message properties: code: type: integer description: > Circle internal status code from the platform `CoreStatusCode` enum (and its domain-specific extensions). **This is not the HTTP status code** — `-1` is the catch-all unknown error, `1`/`2` indicate API parameter problems, `3` is forbidden, `4` is unauthorized, and larger values identify domain-specific failures. Consumers should rely on the HTTP status line for transport-level error class and on this field for the specific Circle error case. example: 2 message: type: string description: >- Internal error message; suitable for logging but not for end-user display. example: API parameter invalid. externalMessage: type: string description: > End-user-displayable error message. Present when the server has generated a customer-facing variant for this error; omitted otherwise. example: The provided amount exceeds the maximum allowed. errors: type: array description: Additional request-field validation errors, when available. items: $ref: '#/components/schemas/ErrorDetail' Id: type: string description: Unique system-generated identifier for the entity. format: uuid example: b8627ae8-732b-4d25-b947-1df8f4007a29 ErrorDetail: type: object required: - error - message properties: error: type: string description: Machine-readable error identifier. example: invalid_value location: type: string description: Query parameter or request field that caused the error. example: assetType message: type: string description: Human-readable description of the specific error. example: The operation and assetType combination is invalid. headers: XRequestId: description: > Circle-generated universally unique identifier (UUID v4). Useful for identifying a specific request when communicating with Circle Support. schema: $ref: '#/components/schemas/XRequestId' responses: BadRequest: description: The request cannot be processed due to a client error. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 2 message: API parameter invalid. NotAuthorized: description: >- The request has not been applied because it lacks valid authentication credentials. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 4 message: Unauthorized. InternalServerError: description: >- The server encountered an unexpected condition that prevented it from fulfilling the request. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/Error' example: code: -1 message: 'Something went wrong. errId: 1f0b0c455e40f753f07b4f0ae6abd4b4' securitySchemes: bearerAuth: type: http scheme: bearer ````