Integrating Outside AWS

Proxylity UDP Gateway's API Gateway destination enables "inside-out" integration, allowing UDP traffic to trigger external HTTP/HTTPS services beyond AWS. This capability bridges UDP protocols to REST APIs across cloud providers, automation platforms, custom webhooks, and enterprise systems—all while maintaining fine-grained IAM security controls.

Architecture Pattern

The integration flow follows this pattern:

1. UDP client sends packet to Proxylity listener
2. Proxylity routes to API Gateway destination with IAM authentication
3. API Gateway transforms request (if using REST API) and calls external HTTP endpoint
4. External service processes request and returns HTTP response
5. API Gateway transforms response (optional) and returns to Proxylity
6. Proxylity sends UDP response back to client

This architecture allows UDP-based devices and protocols to interact with modern HTTP APIs without protocol translation on the client side.

HTTP API vs REST API: Choosing the Right Type

AWS API Gateway offers two API types with different transformation capabilities:

HTTP API - Simple Proxy

Use HTTP API when the external service can accept Proxylity's JSON packet format directly:

• Advantages: Lower cost (~71% cheaper), lower latency, simpler configuration
• Limitations: Minimal request/response transformation—payload passes through as-is
• Best for: Custom services you control that can accept the standard packet format

REST API - Full Transformation

Use REST API when you need to adapt Proxylity's format to match external API schemas:

• Advantages: Full VTL (Velocity Template Language) support for request/response mapping
• Capabilities: Extract fields, restructure JSON, modify headers, add authentication, transform responses
• Best for: Third-party APIs, SaaS platforms, services with strict schema requirements

In practice, most external integrations require REST API because external services expect specific JSON structures that differ from Proxylity's packet format.

VTL Transformation Example

Here's a simple VTL template that transforms Proxylity's packet format to match a typical webhook API:

#set($packet = $input.path('$.Messages[0]'))
{
  "event_type": "udp_packet_received",
  "timestamp": "$packet.ReceivedAt",
  "source_ip": "$packet.Remote.IpAddress",
  "source_port": $packet.Remote.Port,
  "payload": "$packet.Data",
  "metadata": {
    "listener": "$packet.Local.IpAddress:$packet.Local.Port",
    "formatter": "$packet.Formatter"
  }
}

This template extracts specific fields from the first packet in the batch and restructures them to match the external API's expected schema. REST API applies this transformation before sending the request to the backend.

For comprehensive VTL documentation, see AWS's mapping template reference.

Integration Use Cases

IoT Platforms

Send UDP sensor data directly to cloud-based IoT platforms:

Adafruit IO

• Working example: Complete CloudFormation template available in the udp-to-http examples
• Send UDP packets to Adafruit IO feeds using their REST API
• Visualize sensor data on Adafruit IO dashboards without managing servers
• Use case: Environmental sensors → UDP → Proxylity → Adafruit IO → Dashboard + Triggers

Other IoT Platforms

• Similar patterns work with any IoT platform offering HTTP APIs
• ThingSpeak, IoT Central, or custom monitoring dashboards
• VTL transformations adapt Proxylity's packet format to each platform's schema

Cross-Cloud Integration (Potential)

The same architectural pattern enables integration with serverless functions and managed services in other cloud providers:

Google Cloud Platform

• Cloud Functions: Could trigger event-driven functions in GCP from UDP traffic
• Cloud Run: Could invoke containerized HTTP services
• Potential use case: IoT sensors sending UDP data that triggers GCP ML Pipeline for inference

Microsoft Azure

• Azure Functions: Could execute serverless code via HTTP triggers
• Azure Logic Apps: Could start complex workflows from UDP events
• Potential use case: Network monitoring tools sending UDP metrics to Azure Monitor

Automation Platforms (Potential)

Integration patterns that could work with no-code/low-code automation services:

Zapier

• Could trigger Zapier workflows ("Zaps") from UDP packets using webhook triggers
• Connect UDP devices to 5,000+ apps in Zapier's ecosystem
• Potential example: SYSLOG messages → Zapier → Slack notifications + Jira tickets

Make (formerly Integromat)

• Could start Make scenarios via webhook modules
• Complex data transformation and multi-step workflows
• Potential example: Game server UDP stats → Make → Google Sheets + Discord alerts

Other Platforms

• n8n: Self-hosted workflow automation with webhook triggers
• IFTTT: Simple applet chains triggered by webhooks
• Power Automate: Microsoft's automation platform with HTTP triggers

Custom Webhooks

Integrate with custom HTTP services and applications:

Self-Hosted Applications

• Internal web applications with REST APIs
• Custom monitoring dashboards
• Developer tools and CI/CD pipelines
• Example pattern: UDP packet counter → Custom Node.js API → Real-time web dashboard

Microservices

• Bridge UDP protocols to modern microservice architectures
• Enable legacy UDP systems to communicate with new HTTP-based services
• Example pattern: Legacy RADIUS → API Gateway → Modern auth microservice

Partner APIs

• Integrate with business partner HTTP APIs
• B2B data exchange via webhook notifications
• Example: IoT sensor data → Partner analytics API → Shared reporting

Enterprise Connectivity

Reach on-premises and private network services securely:

VPC and PrivateLink

• API Gateway private endpoints accessible only from your VPC
• Use VPC endpoints to call internal HTTP services without internet exposure
• Integration with services connected via AWS PrivateLink

Hybrid Cloud

• Direct Connect: Low-latency, private connection to on-premises data centers
• VPN: Secure tunnel to corporate networks and internal systems
• Use case: UDP monitoring data → API Gateway → On-premises SIEM system

For details on private API Gateway integrations, see AWS documentation on private integrations and private APIs.

IAM-Based Security and Fine-Grained Control

Unlike public webhooks secured only by URL obscurity or shared API keys, API Gateway destinations leverage IAM for robust, auditable access control.

Resource-Level Permissions

IAM policies can restrict Proxylity's access to specific API Gateway endpoints and stages:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowAdafruitIO",
      "Effect": "Allow",
      "Action": "execute-api:Invoke",
      "Resource": "arn:aws:execute-api:us-east-1:123456789012:abc123/prod/POST/adafruit/*"
    },
    {
      "Sid": "AllowCustomDashboard",
      "Effect": "Allow",
      "Action": "execute-api:Invoke",
      "Resource": "arn:aws:execute-api:us-east-1:123456789012:abc123/prod/POST/dashboard"
    }
  ]
}

This policy explicitly authorizes Proxylity to invoke Adafruit IO feed endpoints and a custom dashboard. Any attempt to call other routes will be denied, even if someone discovers the API Gateway URL.

Benefits of IAM Authentication

• Granular control: Permission per endpoint, stage, and HTTP method
• Audit trail: All API invocations logged to CloudTrail for compliance
• No credential sharing: Proxylity assumes a role; no API keys to rotate or leak
• Integration testing: Use separate stages (dev/prod) with different IAM permissions
• Revocable access: Update IAM policy to instantly revoke access without changing API Gateway

Least Privilege Pattern

Following AWS best practices, create destination-specific IAM roles with minimal permissions:

Resources:
  IoTPlatformRole:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Effect: Allow
            Principal:
              AWS: !FindInMap [ProxylityConfig, !Ref "AWS::Region", ServiceRole]
            Action: sts:AssumeRole
            Condition:
              StringEquals:
                sts:ExternalId: !FindInMap [ProxylityConfig, !Ref "AWS::Region", ExternalId]
      Policies:
        - PolicyName: InvokeIoTEndpoint
          PolicyDocument:
            Version: "2012-10-17"
            Statement:
              - Effect: Allow
                Action: execute-api:Invoke
                Resource: !Sub "arn:aws:execute-api:${AWS::Region}:${AWS::AccountId}:${ExternalApi}/prod/POST/iot/*"

This role can only invoke API Gateway endpoints under the /iot/ path, nothing else.

Debugging External Integrations

Debugging external service integrations requires visibility at multiple layers of the request flow.

Layer 1: UDP Payload Capture

Use composite destinations to log the original UDP packet data before any transformation:

Destinations:
  - Name: external-api
    DestinationArn: !Sub "arn:aws:execute-api:${AWS::Region}:${AWS::AccountId}:${ApiGateway}/prod/POST/webhook"
    Role:
      RoleArn: !GetAtt ApiGatewayRole.Arn
  - Name: udp-debug-logs
    DestinationArn: !Sub "arn:aws:logs:${AWS::Region}:${AWS::AccountId}:log-group:/proxylity/udp-packets"
    Role:
      RoleArn: !GetAtt UdpLoggingRole.Arn

This captures the raw UDP data Proxylity received, useful for verifying packet contents before transformation.

Layer 2: API Gateway Execution Logs

Enable CloudWatch logging in API Gateway to see:

• Request received by API Gateway (after IAM auth, before VTL)
• Transformed request sent to backend (after VTL mapping)
• Response from backend
• Transformed response returned to Proxylity
• Error messages and stack traces

Configure logging in your API Gateway stage settings:

ApiGatewayStage:
  Type: AWS::ApiGateway::Stage
  Properties:
    StageName: prod
    RestApiId: !Ref ApiGateway
    DeploymentId: !Ref ApiGatewayDeployment
    AccessLogSetting:
      DestinationArn: !GetAtt ApiGatewayLogGroup.Arn
      Format: '$context.requestId $context.error.message $context.error.messageString'
    MethodSettings:
      - ResourcePath: /*
        HttpMethod: '*'
        LoggingLevel: INFO
        DataTraceEnabled: true

Set DataTraceEnabled: true to log full request/response bodies (be mindful of sensitive data).

Layer 3: External Service Logs

Check the external service's own logging:

• Adafruit IO: Activity feed logs for each feed
• Custom services: Application logs, access logs, error monitoring
• Potential integrations: Cloud Logging (GCP), Application Insights (Azure), Task History (Zapier)

Common Debugging Scenarios

Schema Mismatch

Symptom: External API returns 400 Bad Request or validation errors

Diagnosis: Compare API Gateway execution logs (transformed request) against external API's schema requirements

Solution: Adjust VTL mapping template to match expected schema

Authentication Failures

Symptom: External API returns 401 Unauthorized or 403 Forbidden

Diagnosis: Check if external service requires API keys, OAuth tokens, or specific headers

Solution: Add authentication headers in VTL template or API Gateway integration settings

Timeout Issues

Symptom: API Gateway returns 504 Gateway Timeout

Diagnosis: External service taking longer than API Gateway's 29-second timeout

Solution: Optimize external service or consider async pattern with callback webhook

No Response Received

Symptom: UDP client receives no reply packet

Diagnosis: Check if external API returned a response, and if API Gateway mapped it to Proxylity's response format

Solution: Ensure VTL response template transforms to {"Replies": [...]} format

CloudFormation Example

Complete example showing API Gateway destination with external HTTP integration, IAM role, and composite logging:

AWSTemplateFormatVersion: '2010-09-09'
Description: 'Proxylity UDP to External HTTP via API Gateway'

Resources:
  # API Gateway REST API
  ExternalIntegrationApi:
    Type: AWS::ApiGateway::RestApi
    Properties:
      Name: udp-to-external-api
      Description: Bridge UDP packets to external HTTP services

  # Resource and Method
  WebhookResource:
    Type: AWS::ApiGateway::Resource
    Properties:
      RestApiId: !Ref ExternalIntegrationApi
      ParentId: !GetAtt ExternalIntegrationApi.RootResourceId
      PathPart: webhook

  WebhookMethod:
    Type: AWS::ApiGateway::Method
    Properties:
      RestApiId: !Ref ExternalIntegrationApi
      ResourceId: !Ref WebhookResource
      HttpMethod: POST
      AuthorizationType: AWS_IAM
      Integration:
        Type: HTTP
        IntegrationHttpMethod: POST
        Uri: https://external-service.example.com/api/webhook
        RequestTemplates:
          application/json: |
            #set($packet = $input.path('$.Messages[0]'))
            {
              "event": "udp_packet",
              "data": "$packet.Data",
              "source": "$packet.Remote.IpAddress",
              "timestamp": "$packet.ReceivedAt"
            }
        IntegrationResponses:
          - StatusCode: 200
            ResponseTemplates:
              application/json: |
                {
                  "Replies": []
                }
      MethodResponses:
        - StatusCode: 200

  # Deployment
  ApiDeployment:
    Type: AWS::ApiGateway::Deployment
    DependsOn: WebhookMethod
    Properties:
      RestApiId: !Ref ExternalIntegrationApi
      StageName: prod

  # Proxylity IAM Role
  ProxylityApiGatewayRole:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Effect: Allow
            Principal:
              AWS: !FindInMap [ProxylityConfig, !Ref "AWS::Region", ServiceRole]
            Action: sts:AssumeRole
            Condition:
              StringEquals:
                sts:ExternalId: !FindInMap [ProxylityConfig, !Ref "AWS::Region", ExternalId]
      Policies:
        - PolicyName: InvokeWebhookEndpoint
          PolicyDocument:
            Version: "2012-10-17"
            Statement:
              - Effect: Allow
                Action: execute-api:Invoke
                Resource: !Sub "arn:aws:execute-api:${AWS::Region}:${AWS::AccountId}:${ExternalIntegrationApi}/prod/POST/webhook"

  # CloudWatch Logs for UDP payload debugging
  UdpPayloadLogGroup:
    Type: AWS::Logs::LogGroup
    Properties:
      LogGroupName: /proxylity/udp-payloads
      RetentionInDays: 7

  UdpLoggingRole:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: "2012-10-17"
        Statement:
          - Effect: Allow
            Principal:
              AWS: !FindInMap [ProxylityConfig, !Ref "AWS::Region", ServiceRole]
            Action: sts:AssumeRole
            Condition:
              StringEquals:
                sts:ExternalId: !FindInMap [ProxylityConfig, !Ref "AWS::Region", ExternalId]
      Policies:
        - PolicyName: WriteLogsPolicy
          PolicyDocument:
            Version: "2012-10-17"
            Statement:
              - Effect: Allow
                Action:
                  - logs:CreateLogStream
                  - logs:PutLogEvents
                Resource: !GetAtt UdpPayloadLogGroup.Arn

  # Proxylity Listener with Composite Destinations
  UdpListener:
    Type: Custom::ProxylityUdpGatewayListener
    Properties:
      ServiceToken: !FindInMap [ProxylityConfig, !Ref "AWS::Region", ServiceToken]
      ApiKey: !FindInMap [ProxylityConfig, !Ref "AWS::Region", ApiKey]
      Protocols:
        - udp
      Destinations:
        - Name: external-webhook
          DestinationArn: !Sub "arn:aws:execute-api:${AWS::Region}:${AWS::AccountId}:${ExternalIntegrationApi}/prod/POST/webhook"
          Role:
            RoleArn: !GetAtt ProxylityApiGatewayRole.Arn
        - Name: debug-logging
          DestinationArn: !GetAtt UdpPayloadLogGroup.Arn
          Role:
            RoleArn: !GetAtt UdpLoggingRole.Arn

Outputs:
  UdpEndpoint:
    Description: UDP endpoint for sending packets
    Value: !Sub "${UdpListener.Domain}.proxylity.com:${UdpListener.Port}"
  ApiEndpoint:
    Description: API Gateway endpoint
    Value: !Sub "https://${ExternalIntegrationApi}.execute-api.${AWS::Region}.amazonaws.com/prod/webhook"

Examples and Further Reading

For complete working examples of UDP-to-HTTP integrations, see the udp-to-http folder in our examples repository, which includes:

• GCP Cloud Functions integration
• Azure Functions integration
• Zapier webhook example
• Custom webhook with VTL transformations

Related documentation:

• API Gateway Destinations - Technical reference
• Composite Destinations - Multi-destination patterns
• JSON Packet Format - Request/response packet structure
• Destination Resources - CloudFormation reference