Skip to main content
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 and example payloads for each.

​
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
  }
}