snshttp

README

Amazon SNS HTTP Handler

The snshttp package provides an http.Handler adapter for receiving messages from Amazon SNS over HTTP(s) webhooks. The goal is to reduce the boilerplate necessary to get a new service or endpoint receiving messages from Amazon SNS.

Usage

type EventHandler struct {
  // DefaultHandler provides auto confirmation of subscriptions and ignores
  // unsubscribe events.
  snshttp.DefaultHandler
}

// Notification is called for messages published to the SNS Topic. When using
// DefaultHandler as above this is the only event you need to implement.
func (h *EventHandler) Notification(ctx context.Context, event *snshttp.Notification) error {
  fmt.Printf("id=%q subject=%q message=%q timestamp=%q\n",
    event.MessageID,
    event.Subject,
    event.Message,
    event.Timestamp,
  )

  return nil
}

// snshttp.New returns an http.Handler that will parse the payload and pass the
// event to the provided EventHandler.
snsHandler := snshttp.New(&EventHandler{},
  snshttp.WithAuthentication("sns", "password"),
)

http.Handle("/hooks/sns", snsHandler)

Double Requests

When using authentication Amazon SNS will make an initial request without authentication information to determine which scheme (Basic or Digest) the endpoint is using. Amazon will then make a request using the correct authentication scheme. These double requests will happen for every webhook from SNS but only one will be received by the EventHandler.

Timeouts

Amazon SNS expects a webhook to return a response within 15 seconds, any longer and it considers the request failed and it will try again. Because of this, the context.Context passed to each snshttp.EventHandler receiver has a 15 second timeout set from when the request is received.

Thanks

Continued development is sponsored by Dead Man's Snitch.

Ever been surprised that a critical scheduled task was silently failing to run? Whether it's sending invoices, cache clearing, or backups; Dead Man's Snitch makes it easy to monitor cron jobs and Amazon SNS subscriptions.

Get started with Dead Man's Snitch for free

Documentation

Overview

Package snshttp provides an HTTP handler to make it easier to work with webhooks from Amazon SNS.

Index

• func New(eventHandler EventHandler, opts ...Option) http.Handler
• type DefaultHandler
  • func (h DefaultHandler) SubscriptionConfirmation(ctx context.Context, event *SubscriptionConfirmation) error
  • func (h DefaultHandler) UnsubscribeConfirmation(_ context.Context, _ *UnsubscribeConfirmation) error
• type EventHandler
• type MessageAttribute
  • func (m MessageAttribute) BinaryValue() ([]byte, error)
  • func (m MessageAttribute) StringValue() string
• type Notification
  • func (e *Notification) Unsubscribe(ctx context.Context) error
• type Option
  • func WithAuthentication(username string, password string) Option
• type SubscriptionConfirmation
  • func (e *SubscriptionConfirmation) Confirm(ctx context.Context) error
• type UnsubscribeConfirmation
  • func (e *UnsubscribeConfirmation) Resubscribe(ctx context.Context) error

Functions

func New

func New(eventHandler EventHandler, opts ...Option) http.Handler

New creates a http.Handler for receiving webhooks from an Amazon SNS subscription and dispatching them to the EventHandler. Options are applied in the order they're provided and may clobber previous options.

Types

type DefaultHandler

type DefaultHandler struct{}

DefaultHandler is intended to be mixed in to a struct to provide the most common behavior for event receivers. Adding the DefaultHandler to a struct will automatically confirm subscriptions and ignore any unsubscribe confirmations.

func (DefaultHandler) SubscriptionConfirmation

func (h DefaultHandler) SubscriptionConfirmation(ctx context.Context, event *SubscriptionConfirmation) error

SubscriptionConfirmation confirms the subscription.

func (DefaultHandler) UnsubscribeConfirmation

func (h DefaultHandler) UnsubscribeConfirmation(_ context.Context, _ *UnsubscribeConfirmation) error

UnsubscribeConfirmation does nothing and ignores the event.

type EventHandler

type EventHandler interface {
	// SubscriptionConfirmation is the first event received for a new Amazon SNS
	// webhook subscription and contains information on how to confirm the
	// subscription.
	SubscriptionConfirmation(ctx context.Context, event *SubscriptionConfirmation) error

	// Notification events contain the messages published to the SNS topic. This
	// is the most common type of event.
	Notification(ctx context.Context, event *Notification) error

	// UnsubscribeConfirmation events are sent when the subscription has been
	// canceled and gives the consumer a chance to resubscribe. Note that the
	// UnsubscribeConfirmation event is not sent when deleting a subscription
	// from the console.
	UnsubscribeConfirmation(ctx context.Context, event *UnsubscribeConfirmation) error
}

EventHandler methods are called for each event received from Amazon SNS.

type MessageAttribute

type MessageAttribute struct {
	Type  string `json:"Type"`
	Value string `json:"Value"`
}

func (MessageAttribute) BinaryValue

func (m MessageAttribute) BinaryValue() ([]byte, error)

func (MessageAttribute) StringValue

func (m MessageAttribute) StringValue() string

type Notification

type Notification struct {
	MessageID      string    `json:"MessageId"`
	TopicARN       string    `json:"TopicArn"`
	Subject        string    `json:"Subject"`
	Message        string    `json:"Message"`
	Timestamp      time.Time `json:"Timestamp"`
	UnsubscribeURL string    `json:"UnsubscribeURL"`

	// MessageAttributes contain any attributes added to the message when
	// publishing it to SNS. This is most commonly used when transmitting binary
	// date (using raw message delivery).
	MessageAttributes map[string]MessageAttribute `json:"MessageAttributes"`
}

Notification events are sent for messages that are published to the SNS topic.

func (*Notification) Unsubscribe

func (e *Notification) Unsubscribe(ctx context.Context) error

Unsubscribe will notify Amazon to remove this subscription from the SNS topic. It will make a request to the UnsubscribeURL and error if the request times out or the response does not indicate success.

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option gives a way to customize the SNS handler.

func WithAuthentication

func WithAuthentication(username string, password string) Option

WithAuthentication protects the webhook endpoint behind basic authentication and should be used with HTTPS endpoints as the credentials are basically transmitted in plain text. Either the username, password, or both can be left blank empty. When both are empty authentication will be disabled.

type SubscriptionConfirmation

type SubscriptionConfirmation struct {
	MessageID string    `json:"MessageId"`
	TopicARN  string    `json:"TopicArn"`
	Timestamp time.Time `json:"Timestamp"`

	Token        string `json:"Token"`
	Message      string `json:"Message"`
	SubscribeURL string `json:"SubscribeURL"`
}

SubscriptionConfirmation is an initial event sent by Amazon SNS as part of a handshake before any Notification events can be sent. A call to Confirm or a request to SubscribeURL will finish the handshake and enable Amazon to send Notifications to the webhook.

func (*SubscriptionConfirmation) Confirm

func (e *SubscriptionConfirmation) Confirm(ctx context.Context) error

Confirm finishes the handshake with Amazon, confirming that the subscription should start sending notification. A request is made to the SubscribeURL. An error will be returned if the subscription has already been confirmed.

type UnsubscribeConfirmation

type UnsubscribeConfirmation struct {
	MessageID string    `json:"MessageId"`
	TopicARN  string    `json:"TopicArn"`
	Timestamp time.Time `json:"Timestamp"`

	Token        string `json:"Token"`
	Message      string `json:"Message"`
	SubscribeURL string `json:"SubscribeURL"`
}

UnsubscribeConfirmation events are received when a subscription is canceled via the API. No unsubscribe event is fired when deleting a subscription through the AWS web console.

func (*UnsubscribeConfirmation) Resubscribe

func (e *UnsubscribeConfirmation) Resubscribe(ctx context.Context) error

Resubscribe notifies Amazon to reinstate the subscription. A request is made to the SubscribeURL.