eventsub_framework

README

twitch-eventsub-framework

A small framework for creating Twitch EventSub applications with an HTTP transport.

Note: At the moment, this library does not support the WebSocket transport.

Features

This package has two main features:

1. A SubClient to subscribe to, unsubscribe to, and list subscriptions created with EventSub
2. A SubHandler to handle webhook verification requests and dispatch webhook notifications

Examples

1. See examples/sub_client/main.go for an example usage of creating a new webhook subscription.
2. See examples/sub_handler/main.go for an example usage of receiving webhook notifications from Twitch.

Documentation

Index

• Constants
• func VerifyRequestSignature(req *http.Request, body, secret []byte) (bool, error)
• type Credentials
  • func NewStaticCredentials(clientID string, appToken string) Credentials
• type IDTracker
• type MapTracker
  • func NewMapTracker() *MapTracker
  • func (m *MapTracker) AddAndCheckIfDuplicate(_ context.Context, id string) (bool, error)
• type Status
• type SubClient
  • func NewSubClient(credentials Credentials) *SubClient
  • func NewSubClientHTTP(credentials Credentials, client *http.Client) *SubClient
  • func (s *SubClient) GetSubscriptions(ctx context.Context, statusFilter Status) (*esb.RequestStatus, error)
  • func (s *SubClient) Subscribe(ctx context.Context, srq *SubRequest) (*esb.RequestStatus, error)
  • func (s *SubClient) Unsubscribe(ctx context.Context, subscriptionID string) error
• type SubHandler
  • func NewSubHandler(doSignatureVerification bool, secret []byte) *SubHandler
  • func (s *SubHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type SubRequest
• type TwitchError
  • func (t *TwitchError) Error() string

Constants

const (
	EventSubSubscriptionsEndpoint = "https://api.twitch.tv/helix/eventsub/subscriptions"
)

Functions

func VerifyRequestSignature

func VerifyRequestSignature(req *http.Request, body, secret []byte) (bool, error)

Types

type Credentials

type Credentials interface {
	ClientID() (string, error)
	AppToken() (string, error)
}

Credentials represents a method of obtaining Twitch API client credentials

func NewStaticCredentials

func NewStaticCredentials(clientID string, appToken string) Credentials

NewStaticCredentials creates a Credentials instance with a fixed ClientID string and AppToken string.

This Credentials implementation should only be used for development as the app token will eventually expire and API calls will subsequently fail.

type IDTracker

type IDTracker interface {
	// AddAndCheckIfDuplicate returns if the ID is a duplicate and an error.
	AddAndCheckIfDuplicate(ctx context.Context, id string) (bool, error)
}

type MapTracker

type MapTracker struct {
	// contains filtered or unexported fields
}

MapTracker uses an in-memory map to check if a notification ID is a duplicate.

func NewMapTracker

func NewMapTracker() *MapTracker

NewMapTracker creates a new MapTracker instance which uses an in-memory map to check if a notification ID is a duplicate.

func (*MapTracker) AddAndCheckIfDuplicate

func (m *MapTracker) AddAndCheckIfDuplicate(_ context.Context, id string) (bool, error)

type Status

type Status string

const (
	StatusAny                  Status = ""
	StatusEnabled              Status = "enabled"
	StatusVerificationPending  Status = "webhook_callback_verification_pending"
	StatusVerificationFailed   Status = "webhook_callback_verification_failed"
	StatusFailuresExceeded     Status = "notification_failures_exceeded"
	StatusAuthorizationRevoked Status = "authorization_revoked"
	StatusModeratorRemoved     Status = "moderator_removed"
	StatusUserRemoved          Status = "user_removed"
	StatusVersionRemoved       Status = "version_removed"
)

type SubClient

type SubClient struct {
	// contains filtered or unexported fields
}

func NewSubClient

func NewSubClient(credentials Credentials) *SubClient

NewSubClient creates a new SubClient with the given Credentials provider.

func NewSubClientHTTP

func NewSubClientHTTP(credentials Credentials, client *http.Client) *SubClient

NewSubClientHTTP creates a new SubClient with the given Credentials provider and http.Client instance.

func (*SubClient) GetSubscriptions

func (s *SubClient) GetSubscriptions(ctx context.Context, statusFilter Status) (*esb.RequestStatus, error)

GetSubscriptions returns all EventSub subscriptions. If statusFilter != StatusAny, it will apply the filter to the query.

func (*SubClient) Subscribe

func (s *SubClient) Subscribe(ctx context.Context, srq *SubRequest) (*esb.RequestStatus, error)

Subscribe creates a new Webhook subscription.

func (*SubClient) Unsubscribe

func (s *SubClient) Unsubscribe(ctx context.Context, subscriptionID string) error

Unsubscribe deletes a Webhook subscription by the subscription's ID.

type SubHandler

type SubHandler struct {

	// Challenge handler function.
	// Returns whether the subscription should be accepted.
	VerifyChallenge func(h *esb.ResponseHeaders, chal *esb.SubscriptionChallenge) bool

	// IDTracker used to deduplicate notifications
	IDTracker               IDTracker
	OnDuplicateNotification func(h *esb.ResponseHeaders)

	HandleChannelUpdate func(h *esb.ResponseHeaders, event *esb.EventChannelUpdate)
	HandleChannelFollow func(h *esb.ResponseHeaders, event *esb.EventChannelFollow)
	HandleUserUpdate    func(h *esb.ResponseHeaders, event *esb.EventUserUpdate)

	HandleChannelSubscribe       func(h *esb.ResponseHeaders, event *esb.EventChannelSubscribe)
	HandleChannelSubscriptionEnd func(
		h *esb.ResponseHeaders,
		event *esb.EventChannelSubscriptionEnd,
	)
	HandleChannelSubscriptionGift func(
		h *esb.ResponseHeaders,
		event *esb.EventChannelSubscriptionGift,
	)
	HandleChannelSubscriptionMessage func(
		h *esb.ResponseHeaders,
		event *esb.EventChannelSubscriptionMessage,
	)
	HandleChannelCheer func(h *esb.ResponseHeaders, event *esb.EventChannelCheer)
	HandleChannelRaid  func(h *esb.ResponseHeaders, event *esb.EventChannelRaid)

	HandleChannelBan                 func(h *esb.ResponseHeaders, event *esb.EventChannelBan)
	HandleChannelUnban               func(h *esb.ResponseHeaders, event *esb.EventChannelUnban)
	HandleChannelUnbanRequestCreate  func(h *esb.ResponseHeaders, event *esb.ChannelUnbanRequestCreate)
	HandleChannelUnbanRequestResolve func(h *esb.ResponseHeaders, event *esb.ChannelUnbanRequestResolve)
	HandleChannelModeratorAdd        func(h *esb.ResponseHeaders, event *esb.EventChannelModeratorAdd)
	HandleChannelModeratorRemove     func(h *esb.ResponseHeaders, event *esb.EventChannelModeratorRemove)

	HandleChannelPointsRewardAdd func(
		h *esb.ResponseHeaders,
		event *esb.EventChannelPointsRewardAdd,
	)
	HandleChannelPointsRewardUpdate func(
		h *esb.ResponseHeaders,
		event *esb.EventChannelPointsRewardUpdate,
	)
	HandleChannelPointsRewardRemove func(
		h *esb.ResponseHeaders,
		event *esb.EventChannelPointsRewardRemove,
	)
	HandleChannelPointsRewardRedemptionAdd func(
		h *esb.ResponseHeaders,
		event *esb.EventChannelPointsRewardRedemptionAdd,
	)
	HandleChannelPointsRewardRedemptionUpdate func(
		h *esb.ResponseHeaders,
		event *esb.EventChannelPointsRewardRedemptionUpdate,
	)

	HandleChannelPollBegin    func(h *esb.ResponseHeaders, event *esb.EventChannelPollBegin)
	HandleChannelPollProgress func(h *esb.ResponseHeaders, event *esb.EventChannelPollProgress)
	HandleChannelPollEnd      func(h *esb.ResponseHeaders, event *esb.EventChannelPollEnd)

	HandleChannelPredictionBegin func(
		h *esb.ResponseHeaders,
		event *esb.EventChannelPredictionBegin,
	)
	HandleChannelPredictionProgress func(
		h *esb.ResponseHeaders,
		event *esb.EventChannelPredictionProgress,
	)
	HandleChannelPredictionLock func(
		h *esb.ResponseHeaders,
		event *esb.EventChannelPredictionLock,
	)
	HandleChannelPredictionEnd func(h *esb.ResponseHeaders, event *esb.EventChannelPredictionEnd)

	HandleDropEntitlementGrant func(
		h *esb.ResponseHeaders,
		event *esb.EventDropEntitlementGrant,
	)
	HandleExtensionBitsTransactionCreate func(
		h *esb.ResponseHeaders,
		event *esb.EventBitsTransactionCreate,
	)

	HandleGoalBegin    func(h *esb.ResponseHeaders, event *esb.EventGoals)
	HandleGoalProgress func(h *esb.ResponseHeaders, event *esb.EventGoals)
	HandleGoalEnd      func(h *esb.ResponseHeaders, event *esb.EventGoals)

	HandleHypeTrainBegin    func(h *esb.ResponseHeaders, event *esb.EventHypeTrainBegin)
	HandleHypeTrainProgress func(h *esb.ResponseHeaders, event *esb.EventHypeTrainProgress)
	HandleHypeTrainEnd      func(h *esb.ResponseHeaders, event *esb.EventHypeTrainEnd)

	HandleStreamOnline  func(h *esb.ResponseHeaders, event *esb.EventStreamOnline)
	HandleStreamOffline func(h *esb.ResponseHeaders, event *esb.EventStreamOffline)

	HandleUserAuthorizationGrant  func(h *esb.ResponseHeaders, event *esb.EventUserAuthorizationGrant)
	HandleUserAuthorizationRevoke func(
		h *esb.ResponseHeaders,
		event *esb.EventUserAuthorizationRevoke,
	)

	HandleChannelChatMessage           func(h *esb.ResponseHeaders, event *esb.EventChannelChatMessage)
	HandleChannelChatClear             func(h *esb.ResponseHeaders, event *esb.EventChannelChatClear)
	HandleChannelChatClearUserMessages func(
		h *esb.ResponseHeaders,
		event *esb.EventChannelChatClearUserMessages,
	)
	HandleChannelChatMessageDelete func(
		h *esb.ResponseHeaders,
		event *esb.EventChannelChatMessageDelete,
	)

	HandleChannelChatNotification func(
		h *esb.ResponseHeaders,
		event *esb.EventChannelChatNotification,
	)
	// contains filtered or unexported fields
}

SubHandler implements http.Handler to receive Twitch webhook notifications.

SubHandler handles both verification of new subscriptions and dispatching of event notifications. To handle a specific event, set the corresponding HandleXXX struct field. When a notification is received and validated, the handler function will be invoked in a new goroutine.

func NewSubHandler

func NewSubHandler(doSignatureVerification bool, secret []byte) *SubHandler

func (*SubHandler) ServeHTTP

func (s *SubHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)

type SubRequest

type SubRequest struct {
	// The type of event being subscribed to.
	Type string
	// The parameters under which the event will be fired.
	Condition interface{}
	// The Webhook HTTP callback address.
	Callback string
	// The HMAC secret used to verify the event data.
	Secret string
	// The subscription type version.
	Version string
}

type TwitchError

type TwitchError struct {
	ErrorText string `json:"error"`
	Status    int    `json:"status"`
	Message   string `json:"message"`
}

TwitchError describes an error from the Twitch API.

For example:

{
  "error": "Unauthorized",
  "status": 401,
  "message": "Invalid OAuth token"
}

func (*TwitchError) Error

func (t *TwitchError) Error() string