> ## 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/stablefx.yaml post /v2/stablefx/notifications/subscriptions openapi: 3.1.0 info: title: StableFX API description: > The StableFX API provides endpoints for trading stablecoins. ## Authentication All API requests require authentication using an API key. ## Base URL The base URL for all API endpoints is: `https://api.circle.com/v1/exchange/stablefx` version: 1.0.0 servers: - url: https://api.circle.com description: StableFX API server security: - BearerAuth: [] tags: - name: Quotes description: Endpoints for creating and managing quotes - name: Trades description: Endpoints for creating and managing trades - name: Signatures description: Endpoints for retrieving presign typed data and registering signatures - name: Fees description: Endpoints for retrieving fees - name: Funding description: Endpoints for funding trades - name: Webhook Subscriptions description: Manage subscriptions to notifications - name: Settlement Advance description: Request, track, and repay settlement advances. paths: /v2/stablefx/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/CreateSubscription' responses: '200': content: application/json: schema: $ref: '#/components/schemas/CreateSubscription' description: Successfully created webhook subscription headers: X-Request-Id: $ref: '#/components/headers/XRequestId' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/NotAuthorized' 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: CreateSubscription: 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 will be unrestricted, and a notification is sent for every notification type. If the wildcard (`*`) or any combination of the wildcard and a set of notification types is provided, the webhook will also be unrestricted. If a set of notification types are provided, the webhook will be restricted. The restricted status of the webhook is returned in the response object. Each category of notification types also has a wildcard, which will restrict to all notification types from that category. items: $ref: '#/components/schemas/NotificationType' example: - '*' required: true description: Schema for the request payload to create a new subscription. schemas: CreateSubscription: title: SubscriptionResponse type: object properties: data: $ref: '#/components/schemas/Subscription' XRequestId: type: string description: >- A unique identifier, which can be helpful for identifying a request when communicating with Circle support. example: 2adba88e-9d63-44bc-b975-9b6ae3440dde format: uuid NotificationType: type: string description: > The type of notification that can be subscribed to. Supports wildcard patterns (e.g., 'stablefx.trade.*') to subscribe to all notifications within a category. The '*' wildcard can be used to subscribe to all notifications. enum: - '*' - stablefx.trade.* - stablefx.trade.confirmed - stablefx.trade.pendingSettlement - stablefx.trade.makerFunded - stablefx.trade.makerDelegateFunded - stablefx.trade.takerFunded - stablefx.trade.takerDelegateFunded - stablefx.trade.completed - stablefx.trade.refunded - stablefx.trade.failed - stablefx.trade.breached - stablefx.contract.* - stablefx.contract.recordTrade.failed - stablefx.contract.makerDeliver.failed - stablefx.contract.makerDelegateDeliver.failed - stablefx.contract.takerDeliver.failed - stablefx.contract.takerDelegateDeliver.failed example: stablefx.trade.confirmed 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: Transactions 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: $ref: '#/components/schemas/CreateDate' updateDate: $ref: '#/components/schemas/UpdateDate' 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 will notify on all notification types. A restricted webhook will only notify on the notification types in the `notificationTypes` field. example: false ErrorCode: title: ErrorCode type: integer description: The code that corresponds to the error. enum: - -1 - 0 - 1 - 2 - 3 - 400 - 401 - 403 - 404 DescriptiveError: title: DescriptiveError type: object required: - error - message properties: error: $ref: '#/components/schemas/DescriptiveErrorType' location: type: - string - 'null' description: The key or path where the error occurred message: type: string description: Detailed description of the error Id: type: string format: uuid description: System-generated unique identifier of the resource. example: c4d1da72-111e-4d52-bdbf-2e74a2d803d5 CreateDate: type: string format: date-time description: Date and time when the resource was created example: '2023-01-01T12:04:05Z' UpdateDate: type: string format: date-time description: Date and time when the resource was last updated example: '2023-01-01T12:04:05Z' DescriptiveErrorType: title: DescriptiveErrorType type: string enum: - MISSING_OR_INVALID_FIELD description: Type of descriptive error 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: content: application/json: schema: type: object title: BadRequestResponse required: - code - message properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string description: Human-readable message that describes the error. example: Unknown error occurred errors: type: array description: Array of detailed error descriptions items: $ref: '#/components/schemas/DescriptiveError' example: code: 400 message: Bad request. description: Request cannot be processed due to a client error. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' NotAuthorized: content: application/json: schema: type: object title: NotAuthorizedResponse required: - code - message properties: code: $ref: '#/components/schemas/ErrorCode' message: type: string description: Human-readable message that describes the error. example: Unknown error occurred errors: type: array description: Array of detailed error descriptions items: $ref: '#/components/schemas/DescriptiveError' example: code: 401 message: Malformed authorization. description: >- Request has not been applied because it lacks valid authentication credentials. headers: X-Request-Id: $ref: '#/components/headers/XRequestId' securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: PREFIX:ID:SECRET description: >- Circle's API Keys are formatted in the following structure "PREFIX:ID:SECRET". All three parts are requred to make a successful request. ````