Notifications Quickstart

Circle notifications will inform you every time the status of a resource changes, such as changes in payment status. Notifications can be accessed by setting up a notification subscriber endpoint on your end. This quickstart guide shows how to set up notifications for the Circle APIs. Follow this to configure a subscriber endpoint that sends a notification each time the resource status changes.

Note: This guide addresses the payment resource, but is applicable to any of the resources mentioned in Circle API Notifications.

1. Expose a Subscriber Endpoint

To receive notifications on changes in resource status, you must expose a publicly accessible subscriber endpoint on your side. The endpoint must handle both HEAD and POST requests over HTTPS.

To expose an endpoint for testing, you can use webhook.site to inspect, test and automate incoming HTTPS requests or e-mails directly in the web browser.

Navigate to webhook.site and record the value of the URL shown as Your unique URL:

In the example above, the unique URL is:https://webhook.site/83fa21a0-f00a-4673-bb50-bcf62c78b1f7. Use the public-facing URL you receive as you progress throughout this guide.

2. Subscribe to Status Notifications

Now that you have a publicly accessible endpoint, you need to register your endpoint as a subscriber to webhook notifications by doing the following:

1. Navigate to Developer > Subscriptions in your Circle Mint account and click Add Subscription.

2. Enter your endpoint URL from above. It will be similar to the earlier example: https://webhook.site/83fa21a0-f00a-4673-bb50-bcf62c78b1f7.
3. Click Add Subscription:

4. You should receive two requests on your local server shell that confirm the subscription with a body similar to the following:
   JSON

   {
     "Type" : "SubscriptionConfirmation",
     "MessageId" : "ddbdcdcf-d36a-45b5-927c-da25b9b009ae",
     "Token" : "2336412f37fb687f5d51e6e2425f004aed7b7526d5fae41bc257a0d80532a6820258bf77eb25b90453b863450713a2a5a4250696d725a306ef39962b5b543752c9003e0841c0e61253fd6c517a94edebe44f36c5fe4ba131c8ea5f6f42a43f97f6e1865505e2f29f79a62f89e18f97e03a0dd5d982a7578c8d6e21154163f2d6aae523cff25557f9bc21b2503d413006",
     "TopicArn" : "arn:aws:sns:us-west-2:908968368384:sandbox_platform-notifications-topic",
     "Message" : "You have chosen to subscribe to the topic arn:aws:sns:us-west-2:908968368384:sandbox_platform-notifications-topic.\nTo confirm the subscription, visit the SubscribeURL included in this message.",
     "SubscribeURL" : "https://sns.us-west-2.amazonaws.com/?Action=ConfirmSubscription&TopicArn=arn:aws:sns:us-west-2:908968368384:sandbox_platform-notifications-topic&Token=2336412f37fb687f5d51e6e2425f004aed7b7526d5fae41bc257a0d80532a6820258bf77eb25b90453b863450713a2a5a4250696d725a306ef39962b5b543752c9003e0841c0e61253fd6c517a94edebe44f36c5fe4ba131c8ea5f6f42a43f97f6e1865505e2f29f79a62f89e18f97e03a0dd5d982a7578c8d6e21154163f2d6aae523cff25557f9bc21b2503d413006",
     "Timestamp" : "2020-04-11T20:50:16.324Z",
     "SignatureVersion" : "1",
     "Signature" : "kBr9z/ysQrr0ldowHY4lThkOA+dwyjcsyx7NwkbTkgEKG4N61BSSEA+43aYQEB/Ml09hclybvyjyRKWYOjaxQgbUXWmyWrCQ7vY93WYhuGvOqZxAMPiDiILxLs6/KtOxneKVvzfpK4abLrYyTTA+z/dQ52h9L8eoiSKSW81e4clfYBTJkGmuAPKFC08FvEAVT89VikPp68mBf4CctPv3Em0b4J1VvDhAB21B2LekgUmwUE0aE7fUbsF3XsKGQd/fDshLOJasQEuXSqdB5X7LITBA8r24FY+wCjwm8oR3VI9IMy21fUC6wMgoFIVZHW1KxzpEkMCSe7R1ySdNIru8SQ==",
     "SigningCertURL" : "https://sns.us-west-2.amazonaws.com/SimpleNotificationService-a86cb10b4e1f29c941702d737128f7b6.pem"
   }
   

   CopyCopied!

5. To complete the subscription process, you will need to visit the SubscribeURL from both responses. Until you make a request to this URL, no additional messages will be sent to the endpoint.
6. Once you have visited both SubscribeURLs, your subscription should enter the COMPLETE status to indicate it is ready to use:

You now have a sample local environment ready to receive notifications!

3. Initiate a Transfer to Receive a Notification

To observe a notification message of a transfer resource, follow the Quickstart Guide on sending funds externally with the Accounts API.

Once you successfully initiate a transfer, you should see a notification message on your local server shell that looks similar to the following:
Sample Transfer Notification:

{
  "Type": "Notification",
  "MessageId": "c2fff345-2ff3-5f77-9adb-ae0b05098252",
  "TopicArn": "arn:aws:sns:us-east-1:908968368384:sandbox_platform-notifications-topic",
  "Message": "{\"clientId\":\"2928df09-0b4e-43d7-93cf-7946aad24945\",\"notificationType\":\"transfers\",\"version\":1,\"customAttributes\":{\"clientId\":\"2928df09-0b4e-43d7-93cf-7946aad24945\"},\"transfer\":{\"id\":\"47314bd0-8fe5-4298-86af-ee1ffb9183d9\",\"source\":{\"type\":\"wallet\",\"id\":\"1000037212\"},\"destination\":{\"type\":\"blockchain\",\"address\":\"0x493A9869E3B5f846f72267ab19B76e9bf99d51b1\",\"chain\":\"ETH\"},\"amount\":{\"amount\":\"3.14\",\"currency\":\"USD\"},\"status\":\"pending\",\"createDate\":\"2023-08-10T00:00:58.690Z\"}}",
  "Timestamp": "2023-08-10T00:00:58.891Z",
  "SignatureVersion": "1",
  "Signature": "FPOOJhW0QVkt4NoQFlDtym5g/DYB9M9SBuUXGgH9NNJzzrQ41Xl8LZxHXOZ4r4Qskr2hUKxB1grQ3VAuvhSMP41F/C92Dr8trUSchdEaUTsaGh/y72KhnVqg2QJWAMgC6joeF0v6WgOnzZq/3aBL/GNWAz0wms3PI2wo74gfoCtNAheyAak19rk+tLPyA2/dHf2V9Pd9twV+dorrUEa/kEnL/WGca4TQZsYencRb692dyBVskTmOR9f5oCPUDDk4hPupv5IWTrJv2IhmCBOaTZyK0rEsCVPN7Ozxcmp/YCvp4clOPKCyKwqu04iO4DGwxk6YjdvmHnpXtYx3PzU2Wg==",
  "SigningCertURL": "https://sns.us-east-1.amazonaws.com/SimpleNotificationService-01d088a6f77103d0fe307c0069e40ed6.pem",
  "UnsubscribeURL": "https://sns.us-east-1.amazonaws.com/?Action=Unsubscribe&SubscriptionArn=arn:aws:sns:us-east-1:908968368384:sandbox_platform-notifications-topic:0e94e75d-ba18-4d6b-a3fc-c35b7409ef02",
  "MessageAttributes": {
    "clientId": {
      "Type": "String",
      "Value": "2928df09-0b4e-43d7-93cf-7946aad24945"
    }
  }
}

Congratulations, you have successfully received your first notification on a transfer!