Webhooks

Copy page

Copy page as Markdown for LLMs

Open in Claude

Ask questions about this page

Amazon Payment Services provides real-time webhook notifications to keep your system synchronized with payment statuses. Webhooks ensure you receive transaction updates even when customers don't complete the return flow, making them essential for reliable payment processing.

Overview

Amazon Payment Services offers two types of webhooks for comprehensive transaction monitoring:

• Transaction Feedback - Immediate payment results sent directly after transaction processing
• Notification Feedback - Post-payment updates capture, refund and delayed status changes

Both webhooks use secure server-to-server POST requests in JSON format, ensuring reliable delivery of payment status updates to your backend systems.

Prerequisites

Before implementing webhooks, ensure you have:

1. HTTPS Endpoint
   A secure HTTPS endpoint on your server capable of receiving POST requests. The URL must use your domain name (no IP addresses or port numbers).

2. Response Handler
   Your endpoint must respond with HTTP status codes 2xx (200, 201) or 302 to confirm successful receipt.

Set Up Webhook Endpoints

1

Access Technical Settings

Login to your Amazon Payment Services account and navigate to your Technical Settings tab in your merchant account.

2

Select Integration Type

Select your activated integration type from the available options:

• Hosted Checkout
• Custom Integration
• Mobile SDK

3

Configure Webhook URLs

Configure the following webhook URLs in your selected integration:

• Direct Transaction Feedback URL - For immediate payment results
• Notification URL - For post-payment updates

URL Requirements

Your webhook URLs must meet these requirements:

• HTTPS Protocol - Only secure HTTPS URLs are accepted
• Domain Names Only - No IP addresses or port numbers allowed
• POST Method Support - Must accept HTTP POST requests
• JSON Content Type - Must handle application/json content
• Proper Response Codes - Return 2xx or 302 status codes

Return URL Configuration

Understanding the relationship between return URLs and redirection URLs is crucial for proper payment flow implementation and response handling.

Return URL vs Redirection URL

• Return URL (Request Parameter) The return_url is a parameter you send in your payment request that specifies your implemented endpoint with a controller to handle the payment response received from Amazon Payment Services after payment processing. This endpoint serves as the page where you redirect customers after processing the transaction and display appropriate messages indicating the payment status (success or failure) in your checkout flow.

• Redirection URL (Account Configuration) The redirection_url is configured in your Amazon Payment Services account under Integration Settings → Technical Settings. This URL serves as your default destination for payment responses when no return_url is specified in the request.

When you send a return_url parameter in your payment request, it will override the redirection_url configured in your account for that specific transaction. This allows transaction-specific routing while maintaining a default configuration.

For tokenization transactions, the payment response is exclusively sent to the return_url parameter specified in your request. Ensure you include a valid return_url when processing tokenization requests to receive the token data.

Plugin Configuration

If you are using one of our payment plugins:

1. Copy the Host-to-Host URL from your plugin configuration page
2. Navigate to your Amazon Payment Services account → Integration Settings → Technical Settings
3. Select the required channel (Redirection or Merchant Page)
4. Paste the Host-to-Host URL into all three URL fields displayed:
   • Direct Transaction Feedback URL
   • Notification URL
   • Redirection URL
5. Save your changes

URL Security and Validation

Amazon Payment Services implements comprehensive URL validation to prevent security vulnerabilities. These restrictions apply to all webhook URLs and return URLs configured in your integration:

Blocked URL Patterns

Non-HTTPS Protocols

Blocked: http://example.com/webhook
Blocked: ftp://example.com/webhook
Blocked: file://example.com/webhook
Valid:   https://example.com/webhook

IP Addresses (All Types)

Blocked: https://192.168.1.100/webhook
Blocked: https://10.0.0.1/webhook
Blocked: https://127.0.0.1/webhook
Blocked: https://[::1]/webhook
Valid:   https://api.yourstore.com/webhook

Malformed or Invalid URLs

Blocked: https://example.com:8080/webhook    (port numbers)
Blocked: https://invalid-chars<>/webhook     (invalid characters)
Blocked: not-a-valid-url                     (missing protocol)
Valid:   https://secure.yourstore.com/webhook

DNS and Network Restrictions

• Domains must resolve to public IP addresses
• Private network ranges are blocked for security
• Domains with DNS TTL under 5 seconds are rejected
• URLs returning HTTP redirects (301, 302, 303, 307, 308) are blocked
• Domains without valid DNS records are not accepted

Best Practices

• Use your primary domain or subdomain (e.g., api.yourstore.com)
• Ensure your webhook endpoint is publicly accessible
• Test your URL accessibility before configuration
• Avoid using development or internal domains

These security validation rules apply to:

• Direct Transaction Feedback URL
• Notification URL
• Redirection URL

Support

Need help with webhook implementation? Contact our technical support team at merchantsupport-ps@amazon.com.