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.

💡

Tip:

When you visit webhook.site for the first time, you should see a status message that looks similar to the following:

Your unique URL (Please copy it from here, not from the address bar!) <https://webhook.site/83fa21a0-f00a-4673-bb50-bcf62c78b1f7>

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

   📘

   Note:

   The response body above is in a plain text format, so be sure you're not expecting a JSON content type.

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:

   💡

   Tip:

   If your subscription is stuck in the PENDING (unconfirmed) state, you will need to reach out to [email protected] to remove it.

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!