This quickstart guide helps you quickly configure a notification subscriber endpoint that enables you to easily receive notifications every time the status of a resource changes. This guide will focus on the payment resource, but is applicable to any of the resources mentioned in [Circle API Notifications](🔗).
# 1. Expose a subscriber endpoint
In order to receive notifications on changes in payments status, you will need to expose a publicly accessible subscriber endpoint on your side. That endpoint must be capable of handling both `HEAD` and `POST` requests over `https`.
To quickly expose an endpoint for testing, we have provided the [code for a sample HTTP server](🔗) as part of our sample payments application repository on Github. If you haven't already, follow these [steps to download the sample payments app source code](🔗).
Once you have retrieved the sample code from Github, run the following commands to start the HTTP server containing a sample subscriber endpoint:
You should see a message saying the HTTP server is starting on the desired port.
As this is only a sample server, the easiest way to expose this endpoint externally is to use an ssh tunnel, for example [Localhost.run](🔗).
To run the tunnel, execute the following command on a separate shell.
You should see a status message that looks like the following:
Note the value of the forwarding address (in the example above, `http://a94bca6d-05e8-49a7-b22d-08012366bfe8-d763fbc1.localhost.run`), as that is your public-facing URL to be used in this example. The tunnel supports HTTPs, when needed just replace `http://` with `https://` in the forwarding address.
# 2. Subscribe to payments status notifications
Now you need to register your public endpoint as a subscriber to webhook notifications. This can be completed through:
Circle UI on the Developer section → [Subscriptions](🔗) tab.
[Create a subscription API](🔗) using cURL.
## Circle UI
Through the Circle UI you can set up Webhoook subscriptions by:
Navigating to Developer → Subscriptions in Sandbox or Production.
Selecting Add Subscription
Entering your endpoint URL from above `
https://a94bca6d-05e8-49a7-b22d-08012366bfe8-d763fbc1.localhost.run`.Selecting Add Endpoint
## cURL
When creating a subscription, the `endpoint` you supply will be verified with an initial `HEAD` request. Please make sure the endpoint handles this request and returns a successful (`2xx`) response.
You should receive a response like the following.
Most importantly, at the same time you will receive a request on your local server shell confirming the subscription with a body like the following.
The above body will be returned in a plain text format, so please be sure you're not expecting a JSON content type.
To complete the subscription process, you will need to visit the `SubscribeURL` from this response. Until you make a request to this URL, no additional messages will be sent to the endpoint.
At this stage you have a sample local environment that is ready to receive notifications on payments status changes.
If a customer does not verify the topic ARN when confirming subscriptions, they open themselves up to accepting messages from arbitrary sns topics. They should verify that the topic arn matches the following regular expression: '^arn:aws:sns:.\*:908968368384:(sandbox|prod)\_platform-notifications-topic$'. Please see how verification is done in the [sample HTTP server](🔗)
You can only add one subscriber endpoint per account (API key).
# 3. Initiate a Payment Flow to Receive a Notification
To observe a notification message on the status of a payment, initiate a card payment - for example by following the [Payments API Quickstart guide for card payments](🔗).
Once you process a successful payment, you should see a notification message on your local server shell that looks like the following.
Congratulations, you have received your first notification on a payment! 🎉
# 4. Ready for the next step?
If you are in advanced stages of experimenting with our APIs and want to plan moving to production, please start by [applying for a Circle Account](🔗) and subsequently [reach out to sales](🔗). We'll be happy to walk you through to the next steps.
We can't wait to see what you are going to build!