Skip to main content

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.

During the trade lifecycle, StableFX can send notifications to your subscriber endpoint using webhooks. These asynchronous notifications inform you on the progress of the trade and any issues that may arise. This guide demonstrates how to subscribe to StableFX webhook notifications. This applies to both takers and makers. See the Webhooks section of the API reference for a complete list of the StableFX notifications that are sent over webhooks. See the Trade States page for a summary of the lifecycle of a trade.

​
Steps

Use the following steps to set up a webhook endpoint and subscribe to notifications using the StableFX API.

​
Step 1: Set up a subscriber endpoint

To receive notifications on changes in trade status, you must expose a publicly accessible subscriber endpoint on your side. The endpoint must handle both HEAD and POST requests over HTTPS. When a POST request is received, the endpoint must respond with a 200 OK status code. For testing purposes, you can create an endpoint using webhook.site.

​
Step 2: Subscribe to notifications

Set up your subscriber endpoint to receive notifications from the StableFX API using the Create subscription endpoint. 
curl --request POST \
  --url https://api.circle.com/v2/stablefx/notifications/subscriptions \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer ${YOUR_API_KEY}' \
  --header 'Content-Type: application/json' \
  --data '
{
  "endpoint": "${YOUR_WEBHOOK_ENDPOINT}",
  "notificationTypes": ["*"]
}
'
Example response 
{
  "data": {
    "id": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
    "name": "Transactions Webhook",
    "endpoint": "https://example.org/handler/for/notifications",
    "enabled": true,
    "createDate": "2026-01-01T12:04:05Z",
    "updateDate": "2026-01-01T12:04:05Z",
    "notificationTypes": ["*"],
    "restricted": false
  }
}