gometawebhooks

package module
v0.8.4 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 20, 2024 License: MIT Imports: 11 Imported by: 2

README

Go Meta Webhooks

This project provides a type safe payload verification, validation, parsing and handling for Meta's Webhooks Objects, Fields, and Values event notifications with the following features:

Install

go get github.com/pnmcosta/go-meta-webhooks

Import

import gometawebhooks "github.com/pnmcosta/go-meta-webhooks"

Use Cases

Wire-in this package with any HTTP server package, an example using Echo is provided in the samples directory submodule of this repository.

The example is an implementation of the InstagramHandler which covers supported Instagram field changes and messaging.

Scoped Handlers

You can granually implement each handler for scoped support instead. For example, to only handle InstagramMessageHandler event only instead:

package main

import gometawebhooks "github.com/pnmcosta/go-meta-webhooks"

var _ gometawebhooks.InstagramMessageHandler = (*handler)(nil)

type handler struct{}

func (h handler) InstagramMessage(ctx context.Context, sender, recipient string, sent time.Time, message Message){
    // TODO: implement message handling
}

func main(){
    handler := handler{}
    hooks, err := gometawebhooks.New(
        gometawebhooks.Options.InstagramMessageHandler(handler),
    )

    // TODO: implement HTTP routes see samples directory.
}
Unsupported Objects

Currently only Instagram Webhook objects and fields are explicitly supported, I plan on growing the package over time, however you can implement EntryHandler, ChangesHandler or MessagingHandler to handle events for unsupported objects.

Documentation

Index

Constants

View Source 
const (
	HeaderSignatureName = "X-Hub-Signature-256"
)

Variables

View Source 
var (
	ErrChangesFieldNotImplemented              = errors.New("changes field not implemented")
	ErrInstagramMentionHandlerNotDefined       = errors.New("instagram mentions handler not defined")
	ErrInstagramStoryInsightsHandlerNotDefined = errors.New("instagram story insights handler not defined")
)
View Source 
var (
	ErrMessagingTypeNotImplemented        = errors.New("messaging type not implemented")
	ErrInstagramMessageHandlerNotDefined  = errors.New("instagram message handler not defined")
	ErrInstagramPostbackHandlerNotDefined = errors.New("instagram postback handler not defined")
	ErrInstagramReferralHandlerNotDefined = errors.New("instagram referral handler not defined")
)
View Source 
var (
	ErrObjectRequired     = errors.New("object required")
	ErrObjectNotSupported = errors.New("object not supported")
)
View Source 
var (
	ErrMissingHubSignatureHeader = errors.New("missing signature value")
	ErrHMACVerificationFailed    = errors.New("HMAC verification failed")
	ErrParsingPayload            = errors.New("parsing payload")
	ErrInvalidPayload            = errors.New("invalid payload")
)
View Source 
var (
	ErrSchemaCompile = errors.New("failed to compile schema")
	ErrMissingSchema = errors.New("missing embedded schema")
)
View Source 
var (
	ErrApplyingOption = errors.New("error applying option")
)
View Source 
var (
	ErrParsingEntry = errors.New("parsing entry")
)
View Source 
var (
	ErrVerifyTokenFailed = errors.New("invalid verify_token value")
)
View Source 
var Options = MetaWebhookOptions{}

Options is a namespace var for configuration options

Functions

This section is empty.

Types

type Attachment 

type Attachment struct {
	Type    string            `json:"type,omitempty"`
	Payload AttachmentPayload `json:"payload,omitempty"`
}

type AttachmentPayload added in v0.3.0 

type AttachmentPayload struct {
	URL         string `json:"url,omitempty"`
	Title       string `json:"title,omitempty"`
	StickerId   string `json:"sticker_id,omitempty"`
	ReelVideoId string `json:"reel_video_id,omitempty"`
}

type Change 

type Change struct {
	Field string      `json:"field,omitempty"`
	Value interface{} `json:"value,omitempty"`
}

func (*Change) UnmarshalJSON 

func (c *Change) UnmarshalJSON(data []byte) error

type Entry 

type Entry struct {
	Id        string      `json:"id"`
	Time      int64       `json:"time"`
	Messaging []Messaging `json:"messaging,omitempty"`
	Changes   []Change    `json:"changes,omitempty"`
}

func (*Entry) UnmarshalJSON added in v0.7.0 

func (t *Entry) UnmarshalJSON(b []byte) error

type Event 

type Event struct {
	Object Object  `json:"object"`
	Entry  []Entry `json:"entry"`
}

type InstagramChangesHandler 

type InstagramChangesHandler interface {
	InstagramMentionHandler
	InstagramStoryInsightsHandler
}

type InstagramHandler 

type InstagramHandler interface {
	InstagramChangesHandler
	InstagramMessagingHandler
}

type InstagramMentionHandler 

type InstagramMentionHandler interface {
	InstagramMention(ctx context.Context, object Object, entry Entry, mention Mention) error
}

type InstagramMessageHandler 

type InstagramMessageHandler interface {
	InstagramMessage(ctx context.Context, object Object, entry Entry, message MessagingMessage) error
}

type InstagramMessagingHandler 

type InstagramMessagingHandler interface {
	InstagramMessageHandler
	InstagramPostbackHandler
	InstagramReferralHandler
}

type InstagramPostbackHandler 

type InstagramPostbackHandler interface {
	InstagramPostback(ctx context.Context, object Object, entry Entry, postback MessagingPostback) error
}

type InstagramReferralHandler 

type InstagramReferralHandler interface {
	InstagramReferral(ctx context.Context, object Object, entry Entry, referral MessagingReferral) error
}

type InstagramStoryInsightsHandler 

type InstagramStoryInsightsHandler interface {
	InstagramStoryInsights(ctx context.Context, object Object, entry Entry, storyInsights StoryInsights) error
}

type Mention added in v0.8.0 

type Mention struct {
	MediaID   string `json:"media_id,omitempty"`
	CommentID string `json:"comment_id,omitempty"`
}

type Message 

type Message struct {
	Id          string       `json:"mid,omitempty"`
	Text        string       `json:"text,omitempty"`
	Attachments []Attachment `json:"attachments,omitempty"`
	Referral    *Referral    `json:"referral,omitempty"`

	IsDeleted     bool `json:"is_deleted,omitempty"`
	IsEcho        bool `json:"is_echo,omitempty"`
	IsUnsupported bool `json:"is_unsupported,omitempty"`

	ReplyTo *struct {
		// one
		Id string `json:"mid,omitempty"`
		// or another
		Story *struct {
			ID  string `json:"id,omitempty"`
			URL string `json:"url,omitempty"`
		} `json:"story,omitempty"`
	} `json:"reply_to,omitempty"`

	QuickReply *struct {
		Payload string `json:"payload,omitempty"`
	} `json:"quick_reply,omitempty"`
}

type Messaging 

type Messaging struct {
	Type interface{} `json:"-"`
}

Wrapper struct for types MessagingMessage, MessagingPostback and MessagingReferral

func (*Messaging) UnmarshalJSON added in v0.8.0 

func (t *Messaging) UnmarshalJSON(b []byte) error

type MessagingHeader added in v0.8.0 

type MessagingHeader struct {
	Sender struct {
		Id string `json:"id"`
	} `json:"sender"`
	Recipient struct {
		Id string `json:"id"`
	} `json:"recipient"`
	Timestamp int64 `json:"timestamp"`
}

type MessagingMessage added in v0.8.0 

type MessagingMessage struct {
	MessagingHeader

	Message Message `json:"message,omitempty"`
}

https://developers.facebook.com/docs/messenger-platform/instagram/features/webhook/#messages

type MessagingPostback added in v0.8.0 

type MessagingPostback struct {
	MessagingHeader

	Postback Postback `json:"postback,omitempty"`
}

https://developers.facebook.com/docs/messenger-platform/instagram/features/webhook/#messaging-postbacks

type MessagingReferral added in v0.8.0 

type MessagingReferral struct {
	MessagingHeader

	Referral Referral `json:"referral,omitempty"`
}

https://developers.facebook.com/docs/messenger-platform/instagram/features/webhook/#igme

type MetaWebhookOptions 

type MetaWebhookOptions struct{}

MetaWebhookOptions is a namespace for configuration option methods

func (MetaWebhookOptions) CompileSchema added in v0.5.0 

func (MetaWebhookOptions) CompileSchema() Option

Ensures embedded JSON schema is compiled

func (MetaWebhookOptions) CustomHeaderSigName added in v0.5.0 

func (MetaWebhookOptions) CustomHeaderSigName(name string) Option

Sets a custom header signature name

func (MetaWebhookOptions) IgnoreEchoMessages added in v0.8.0 

func (MetaWebhookOptions) IgnoreEchoMessages(ignore bool) Option

func (MetaWebhookOptions) InstagramChangesHandler 

func (MetaWebhookOptions) InstagramChangesHandler(fn InstagramChangesHandler) Option

Sets all InstagramChanges handlers

func (MetaWebhookOptions) InstagramHandler 

func (MetaWebhookOptions) InstagramHandler(fn InstagramHandler) Option

Sets all Instagram handlers

func (MetaWebhookOptions) InstagramMentionHandler 

func (MetaWebhookOptions) InstagramMentionHandler(fn InstagramMentionHandler) Option

Sets the InstagramMentionHandler, see https://developers.facebook.com/docs/instagram-api/guides/mentions

func (MetaWebhookOptions) InstagramMessageHandler 

func (MetaWebhookOptions) InstagramMessageHandler(fn InstagramMessageHandler) Option

Sets the InstagramMessageHandler, see https://developers.facebook.com/docs/messenger-platform/instagram/features/webhook/#messages

func (MetaWebhookOptions) InstagramMessagingHandler 

func (MetaWebhookOptions) InstagramMessagingHandler(fn InstagramMessagingHandler) Option

Sets all InstagramMessaging handlers

func (MetaWebhookOptions) InstagramPostbackHandler 

func (MetaWebhookOptions) InstagramPostbackHandler(fn InstagramPostbackHandler) Option

Sets the InstagramPostbackHandler, see https://developers.facebook.com/docs/messenger-platform/instagram/features/webhook/#messaging-postbacks

func (MetaWebhookOptions) InstagramReferralHandler 

func (MetaWebhookOptions) InstagramReferralHandler(fn InstagramReferralHandler) Option

Sets the InstagramReferralHandler, see https://developers.facebook.com/docs/messenger-platform/instagram/features/webhook/#igme

func (MetaWebhookOptions) InstagramStoryInsightsHandler 

func (MetaWebhookOptions) InstagramStoryInsightsHandler(fn InstagramStoryInsightsHandler) Option

Sets the InstagramStoryInsightsHandler, see https://developers.facebook.com/docs/instagram-api/guides/webhooks#capturing-story-insights

func (MetaWebhookOptions) Secret 

func (MetaWebhookOptions) Secret(secret string) Option

Sets the Facebook APP Secret

func (MetaWebhookOptions) Token 

func (MetaWebhookOptions) Token(token string) Option

Sets the Facebook APP webhook subscription verify token

type Object 

type Object string
const (
	Instagram Object = "instagram"
)

func (*Object) FromString 

func (t *Object) FromString(status string) Object

func (Object) MarshalJSON 

func (t Object) MarshalJSON() ([]byte, error)

func (Object) String 

func (t Object) String() string

func (*Object) UnmarshalJSON 

func (t *Object) UnmarshalJSON(b []byte) error

type Option 

type Option func(*Webhooks) error

Option is a configuration option for the webhook

type Postback 

type Postback struct {
	Id       string    `json:"mid,omitempty"`
	Title    string    `json:"title,omitempty"`
	Payload  string    `json:"payload,omitempty"`
	Referral *Referral `json:"referral,omitempty"`
}

type Referral 

type Referral struct {
	Type    string `json:"type,omitempty"`
	Source  string `json:"source,omitempty"`
	Ref     string `json:"ref,omitempty"`
	Product *struct {
		Id string `json:"id,omitempty"`
	} `json:"product,omitempty"`
}

type StoryInsights added in v0.8.0 

type StoryInsights struct {
	MediaID     string `json:"media_id,omitempty"`
	Exits       int    `json:"exits,omitempty"`
	Replies     int    `json:"replies,omitempty"`
	Reach       int    `json:"reach,omitempty"`
	TapsForward int    `json:"taps_forward,omitempty"`
	TapsBack    int    `json:"taps_back,omitempty"`
	Impressions int    `json:"impressions,omitempty"`
}

type Webhooks 

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

Webhooks instance contains all methods needed to process object events

func New 

func New(options ...Option) (*Webhooks, error)

Creates and returns a webhooks instance

func (Webhooks) Handle 

func (h Webhooks) Handle(ctx context.Context, event Event) error

func (Webhooks) ParsePayload added in v0.6.0 

func (hooks Webhooks) ParsePayload(body []byte) (Event, error)

func (Webhooks) ValidatePayload added in v0.6.0 

func (hooks Webhooks) ValidatePayload(body []byte) error

func (Webhooks) VerifyPayload added in v0.6.0 

func (hooks Webhooks) VerifyPayload(body []byte, headers map[string]string) error

func (Webhooks) VerifyToken added in v0.5.1 

func (hooks Webhooks) VerifyToken(queryValues map[string]string) (string, error)

type WebhooksHandler added in v0.6.0 

type WebhooksHandler interface {
	Handle(context.Context, Event) error
}

Source Files

View all Source files

Directories

Path Synopsis
samples
echo Module
serve Module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.