IoE Webhooks

Overview

OpenTech Alliance allows for the option to subscribe, via a webhook, to Gateway Events.

Webhooks are implemented using AWS Subscriptions to a SNS Gateway Event Topic.

Process

OpenTech Alliance support will create the AWS subscription for the https endpoint that you provide.

What You Will Need to Do

Before OpenTech Alliance support can create the AWS subscription, your technical team must first create the webhook.

The webhook would be a publicly available https endpoint that is ready to accept and respond to:

A “SubscriptionConfirmation” request.
- Notification messages will not be sent until a Subscription Confirmation response has been received.
“Notification” messages (the Gateway Events).

See https://docs.aws.amazon.com/sns/latest/dg/SendMessageToHttp.prepare.html for detailed information on the messages that will be sent ( “SubscriptionConfirmation” and “Notification”), and how they should be processed.

Payload

For a “Notification”, the payload (i.e. Gateway Event data) will be in the “Message” portion of the data received.

The “Message” portion of the data will be Json formatted and will look something like:

Note that in the .NET example below the AWS SNS SDK puts the “Message” into the Message.MessageText field.

Example Code - .NET

Below is a simple .NET web server example that uses the AWSSDK.SimpleNotificationService nuget to parse and check the incoming message.

Other Development Languages

Amazon has SDKs for other development languages that may be of help.

See https://docs.aws.amazon.com/ for additional SDKs & toolkits.

NOTE:

Probably the most complicated part of processing an incoming message is verifying the signatures of an Amazon SNS message (should be done for security purposes).

See https://docs.aws.amazon.com/sns/latest/dg/sns-verify-signature-of-message.html

This is easily handled in the .NET example above via the AWS SDK for .NET.

This may not be the case for other SDKs though. E.g. the current AWS SDK for Java 2.x does not appear to include that functionality, although the AWS SDK for Java 1.x (no longer under support) does.