webhooks

README

Webhooks

Webhooks service provides forwarding received messages to other platforms.

Configuration

The service is configured using the environment variables from the following table. Note that any unset variables will be replaced with their default values.

Variable	Description	Default
MF_WEBHOOKS_LOG_LEVEL	Log level for Webhooks (debug, info, warn, error)	error
MF_WEBHOOKS_DB_HOST	Database host address	localhost
MF_WEBHOOKS_DB_PORT	Database host port	5432
MF_WEBHOOKS_DB_USER	Database user	mainflux
MF_WEBHOOKS_DB_PASS	Database password	mainflux
MF_WEBHOOKS_DB	Name of the database used by the service	webhooks
MF_WEBHOOKS_DB_SSL_MODE	Database connection SSL mode (disable, require, verify-ca, verify-full)	disable
MF_WEBHOOKS_DB_SSL_CERT	Path to the PEM encoded certificate file
MF_WEBHOOKS_DB_SSL_KEY	Path to the PEM encoded key file
MF_WEBHOOKS_DB_SSL_ROOT_CERT	Path to the PEM encoded root certificate file
MF_WEBHOOKS_CLIENT_TLS	Flag that indicates if TLS should be turned on	false
MF_WEBHOOKS_CA_CERTS	Path to trusted CAs in PEM format
MF_WEBHOOKS_HTTP_PORT	Webhooks service HTTP port	9021
MF_WEBHOOKS_SERVER_CERT	Path to server certificate in pem format
MF_WEBHOOKS_SERVER_KEY	Path to server key in pem format
MF_JAEGER_URL	Jaeger server URL	localhost:6831
MF_BROKER_URL	Message broker URL	nats://127.0.0.1:4222
MF_THINGS_AUTH_GRPC_URL	Things auth service gRPC URL	localhost:8183
MF_THINGS_AUTH_GRPC_TIMEOUT	Things auth service gRPC request timeout in seconds	1s

Deployment

The service is distributed as a Docker container. Check the webhooks service section in docker-compose to see how service is deployed.

To start the service outside of the container, execute the following shell script:

# download the latest version of the service
go get github.com/MainfluxLabs/mainflux

cd $GOPATH/src/github.com/MainfluxLabs/mainflux

# compile the webhooks
make webhooks

# copy binary to bin
make install

# set the environment variables and run the service
MF_WEBHOOKS_LOG_LEVEL=[Webhooks log level]
MF_WEBHOOKS_DB_HOST=[Database host address]
MF_WEBHOOKS_DB_PORT=[Database host port]
MF_WEBHOOKS_DB_USER=[Database user]
MF_WEBHOOKS_DB_PASS=[Database password]
MF_WEBHOOKS_DB=[Name of the database used by the service]
MF_WEBHOOKS_DB_SSL_MODE=[SSL mode to connect to the database with]
MF_WEBHOOKS_DB_SSL_CERT=[Path to the PEM encoded certificate file]
MF_WEBHOOKS_DB_SSL_KEY=[Path to the PEM encoded key file]
MF_WEBHOOKS_DB_SSL_ROOT_CERT=[Path to the PEM encoded root certificate file]
MF_WEBHOOKS_CLIENT_TLS=[Flag that indicates if TLS should be turned on]                                           
MF_WEBHOOKS_CA_CERTS=[Path to trusted CAs in PEM format]                            
MF_WEBHOOKS_HTTP_PORT=[Service HTTP port]
MF_WEBHOOKS_SERVER_CERT=[String path to server cert in pem format]
MF_WEBHOOKS_SERVER_KEY=[String path to server key in pem format]
MF_JAEGER_URL=[Jaeger server URL]
MF_BROKER_URL=[Message broker URL]
MF_THINGS_AUTH_GRPC_URL=[Things auth service gRPC URL]
MF_THINGS_AUTH_GRPC_TIMEOUT=[Things auth service gRPC request timeout in seconds]
$GOBIN/mainflux-kit

Usage

For more information about service capabilities and its usage, please check out the API documentation.

Documentation

Index

• Variables
• type Forwarder
  • func NewForwarder() Forwarder
• type Metadata
• type PageMetadata
• type Service
  • func New(things protomfx.ThingsServiceClient, webhooks WebhookRepository, ...) Service
• type Webhook
• type WebhookRepository
• type WebhooksPage

Variables

var ErrForward = errors.New("failed to forward message")

Types

type Forwarder

type Forwarder interface {
	// Forward method is used to forward the received message to a certain url
	Forward(ctx context.Context, message mfjson.Message, wh Webhook) error
}

func NewForwarder

func NewForwarder() Forwarder

type Metadata

type Metadata map[string]interface{}

type PageMetadata

type PageMetadata struct {
	Total    uint64
	Offset   uint64                 `json:"offset,omitempty"`
	Limit    uint64                 `json:"limit,omitempty"`
	Name     string                 `json:"name,omitempty"`
	Order    string                 `json:"order,omitempty"`
	Dir      string                 `json:"dir,omitempty"`
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

type Service

type Service interface {
	// CreateWebhooks creates webhooks for certain group identified by the provided ID
	CreateWebhooks(ctx context.Context, token string, webhooks ...Webhook) ([]Webhook, error)

	// ListWebhooksByGroup retrieves data about a subset of webhooks
	// related to a certain group identified by the provided ID.
	ListWebhooksByGroup(ctx context.Context, token, groupID string, pm PageMetadata) (WebhooksPage, error)

	// ViewWebhook retrieves data about the webhook identified with the provided
	// ID, that belongs to the user identified by the provided key.
	ViewWebhook(ctx context.Context, token, id string) (Webhook, error)

	// UpdateWebhook updates the webhook identified by the provided ID, that
	// belongs to the user identified by the provided key.
	UpdateWebhook(ctx context.Context, token string, webhook Webhook) error

	// RemoveWebhooks removes the webhooks identified with the provided IDs, that
	// belongs to the user identified by the provided key.
	RemoveWebhooks(ctx context.Context, token string, id ...string) error

	consumers.Consumer
}

Service specifies an API that must be fullfiled by the domain service implementation, and all of its decorators (e.g. logging & metrics).

func New

func New(things protomfx.ThingsServiceClient, webhooks WebhookRepository, forwarder Forwarder, idp uuid.IDProvider) Service

New instantiates the webhooks service implementation.

type Webhook

type Webhook struct {
	ID       string
	GroupID  string
	Name     string
	Url      string
	Headers  map[string]string
	Metadata Metadata
}

type WebhookRepository

type WebhookRepository interface {
	// Save persists multiple webhooks. Webhooks are saved using a transaction.
	// If one webhook fails then none will be saved.
	// Successful operation is indicated by non-nil error response.
	Save(ctx context.Context, whs ...Webhook) ([]Webhook, error)

	// RetrieveByGroupID retrieves webhooks related to
	// a certain group identified by a given ID.
	RetrieveByGroupID(ctx context.Context, groupID string, pm PageMetadata) (WebhooksPage, error)

	// RetrieveByID retrieves the webhook having the provided identifier
	RetrieveByID(ctx context.Context, id string) (Webhook, error)

	// Update performs an update to the existing webhook. A non-nil error is
	// returned to indicate operation failure.
	Update(ctx context.Context, w Webhook) error

	// Remove removes the webhooks having the provided identifiers
	Remove(ctx context.Context, ids ...string) error
}

type WebhooksPage

type WebhooksPage struct {
	PageMetadata
	Webhooks []Webhook
}