Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Receiving Notifications via Webhooks

In addition to handling the payment completion redirect, you may want to use webhooks as a transaction status delivery mechanism.

Webhooks provide a reliable server-to-server fallback in case the client-side redirect doesn't return a response due to connectivity issues or the user closing their browser too early. They are sent asynchronously (usually within seconds with a retry mechanism) for all transaction results.

Hyp Enterprise push notifications are powered by Amazon SNS (Simple Notification Service). When you register a webhook endpoint in the Hyp Console, Amazon SNS starts sending POST requests that deliver transaction notifications to your receiver application.

Prerequisites

Before you enable webhooks, set up a receiver application — either a custom application or a third-party webhook service — that exposes an endpoint prepared to handle the POST requests sent by Amazon SNS. The receiver application must meet the following requirements:

  • HTTPS: Your receiver application must use a server certificate signed by a trusted Certificate Authority (CA). Amazon SNS will not send messages to endpoints with self-signed or untrusted certificates.

  • Initial confirmation: Your receiver application must be able to receive and process the initial SubscriptionConfirmation message sent by Amazon SNS when you register a webhook subscription.

  • Response status and timeout: Your receiver application must respond to every notification with a successful status code in the 200–4xx range within 15 seconds. If the connection times out or returns an error, Amazon SNS will consider the delivery attempt failed and will retry according to its retry policy.

  • Firewall settings: The firewall protecting your receiver application's endpoint must allow traffic from Amazon SNS. If you use a service like Cloudflare, you may need to whitelist the Amazon Simple Notification Service Agent User-Agent.

There are two approaches that you can use to fulfill these prerequisites.

Approach 1: Third-party webhook services (best for testing)

During development or sandbox testing, you can route traffic to an external webhook monitoring service like webhook.site.

  • How it handles confirmations: Webhook services do not automatically confirm the subscription. You must open the service's dashboard, locate the SubscriptionConfirmation JSON payload, and manually copy/paste the SubscribeURL into your browser to activate it.

  • How it handles notifications: Once manually confirmed, subsequent transaction notifications will appear in your third-party dashboard for visual inspection and debugging. Webhook services will normally automatically reply to Amazon SNS with a 200 OK status code.

Approach 2: Custom receiver application (best for production)

You deploy a dedicated endpoint within your own software stack (e.g., an Express.js, Python, or .NET backend).

  • How it handles confirmations: Your application code needs to intercept the initial SubscriptionConfirmation notification, extract the SubscribeURL, and programmatically send a GET request to it to activate the subscription.

  • How it handles notifications: Once confirmed, your receiver application needs to automatically parse incoming transaction notifications, auto-reply to them, and update your internal database or order status.

When developing a custom receiver application, follow Amazon's guidelines on preparing to process SNS messages. In addition, mind the following:

  • You can use the x-amz-sns-message-type header of the POST requests that Amazon SNS sends to your endpoint to determine the message type without having to parse the body of the HTTPS request. The possible values are:

    • SubscriptionConfirmation – sent for one-time subscription confirmation.

    • Notification – sent for each Hyp Enterprise transaction.

    • UnsubscribeConfirmation – sent when you choose to unsubscribe from webhook notifications.

  • You can use the x-amz-sns-message-id header to compare the IDs of the messages you have already processed with incoming messages. This will help you determine whether a message is new or represents a retry attempt.

  • For guidance on parsing POST requests from Amazon SNS, see Parsing Amazon SNS message formats.

  • To ensure message authenticity and integrity and prevent spoofing, Amazon's best practice recommendation is that you verify every SNS message. For an up-to-date verification guide, see Verifying the signature of an Amazon SNS message when using HTTP query-based requests.

Setting up webhooks

Setting up webhooks is a two-part process: first, you create a new webhook subscription in your Hyp Console, and then you confirm the subscription.

Creating a webhook subscription

  1. In your Hyp Console, click Manage in the sidebar.

  2. Under Webhook Service Management, select Payment page: Hyp Console sidebar

  3. Click New Subscription.

  4. In the Receiving Automatic Updates via WEBHOOK form, fill in the following details:

    • Subscription Name: A descriptive name for this webhook (e.g., "Production Webhook").

    • ENDPOINT Address: The full HTTPS URL of your receiver application's endpoint where you want to receive notifications.

    • Alert Format: Select whether you want to receive the transaction data in JSON or XML format.

    • Terminal Selection: Choose whether to receive notifications for All Terminals or select specific terminals from the list.

  5. Click Register for Service.

The new subscription will be created in the Pending Approval status. Meanwhile, an Amazon SNS confirmation request will be sent to your defined endpoint.

Confirming your subscription

Look for a message of type SubscriptionConfirmation from Amazon SNS:

Show a SubscriptionConfirmation message example

To start receiving notifications, your receiver application must:

  1. Extract a URL from the SubscribeURL field of the request body.

  2. Perform an HTTP GET request to that URL to confirm the subscription.

Once confirmed, the endpoint subscription in your Hyp Console will be marked as active, and Amazon SNS will begin sending transaction notifications to the endpoint.

Processing transaction notifications

When a transaction occurs, Amazon SNS sends a Notification message:

Show a transaction notification example

The actual transaction data is contained within the Message field of the JSON body. This field contains a Base64-encoded string that you should decode to retrieve the raw transaction data.

Once decoded, the result is a JSON or XML document describing the transaction. When structured as XML, this document follows the exact same structure as a transaction inquiry response:

Show an XML document decoded from the Message field
Show a JSON document decoded from the Message field

Unsubscribing from notifications

If you want to unsubscribe and stop receiving webhook notifications to your endpoint, you can do this in one of two ways:

  1. In your Hyp Console (recommended):

    1. Click Manage in the sidebar.

    2. Select Webhook Service Management, then Payment Page.

    3. In the list of webhook subscriptions, click the three-dot menu next to the subscription you want to unsubscribe from.

    4. Click Remove Subscription.

  2. Perform a GET request to the URL provided in the UnsubscribeURL property of any transaction notification you've received before.

Last updated

Was this helpful?