convoy

README

Convoy

• Website: https://getconvoy.io
• Forum: Github Discussions
• Documentation: getconvoy.io/docs
• Announcement: Medium
• Slack: Slack

Convoy is a fast & secure webhooks service. It receives event data from a HTTP API and sends these event data to the configured endpoints. To get started download the openapi spec into Postman or Insomnia.

It includes the following features

• Sign payload: Configure hash function to use in signing payload.
• Retry events: Retry events to endpoints.
• Delivery Attempt Logs: View request headers and body as well as response headers and body.
• Rich UI: To easily debug and retry failed events.

Install

There are various ways of installing Convoy.

Precompiled binaries

Precompiled binaries for released versions are available in the releases section on Github.

Docker images

Docker images are available on Github Container Registry.

You can launch a Convoy Container to try it out with

$ docker run \
	-p 5005:5005 \
	--name convoy-server \
	-v `pwd`/convoy.json:/convoy.json \
	ghcr.io/frain-dev/convoy:v0.3.0

You can download a sample configuration of convoy.json.

Building from source

To build Convoy from source code, you need:

• Go version 1.16 or greater.
• NodeJS version 14.17 or greater.
• Npm version 6 or greater.

git clone https://github.com/frain-dev/convoy.git && cd convoy
go build -o convoy ./convoy

Concepts

1. Apps: An app is an abstraction representing a user who wants to receive webhooks. Currently, an app contains one endpoint to receive webhooks.
2. Events: An event represents a webhook event to be sent to an app.
3. Delivery Attempts: A delivery attempt represents an attempt to send an event to it's respective app's endpoint. It contains the event body, status code and response body received on attempt. The amount of attempts on a failed delivery depends on your configured retry strategy.

Configuration

Convoy is configured using a json file with a sample configuration below:

{
	"database": {
		"dsn": "mongo-url-with-username-and-password"
	},
	"queue": {
		"type": "redis",
		"redis": {
			"dsn": "redis-url-with-username-and-password"
		}
	},
	"server": {
		"http": {
			"port": 5005
		}
	},
	"auth": {
		"type": "none"
	},
	"group": {
		"strategy": {
			"type": "default",
			"default": {
				"intervalSeconds": 125,
				"retryLimit": 15
			}
		},
		"signature": {
			"header": "X-Company-Event-Webhook-Signature"
		}
	}
	"environment": "development",
	"disable_endpoint": false
	"multiple_tenants": false
}

Notes to Configuration

• You can set basic auth mechanism with the following:

{
	"auth": {
		"type": "basic",
		"basic": {
			"username": "username",
			"password": "password"
		}
	}
}

License

Mozilla Public License v2.0

Documentation

Index

• Constants
• Variables
• type HttpMethod
• type Plugin
• type SentryHook
  • func NewSentryHook(levels []log.Level) *SentryHook
  • func (s *SentryHook) Fire(entry *log.Entry) error
  • func (s *SentryHook) Levels() []log.Level
• type TaskName
  • func (t TaskName) SetPrefix(prefix string) TaskName

Constants

const (
	// With this Convoy will not process more than 3000
	// concurrent requests per minute. We use github.com/go-chi/httprate
	// which uses a sliding window algorithm, so we should be fine :)
	// TODO(subomi): We need to configure rate limiting to be per
	// client as well as implement distributed limiting backed by
	// a distributed key value store.
	RATE_LIMIT          = 5000
	RATE_LIMIT_DURATION = 1 * time.Minute
)

Variables

var DefaultLevels = []log.Level{
	log.ErrorLevel,
	log.PanicLevel,
	log.FatalLevel,
	log.WarnLevel,
}

Types

type HttpMethod

type HttpMethod string

const (
	HttpPost HttpMethod = "POST"
)

type Plugin

type Plugin interface {
	Apply(http.ResponseWriter, *http.Request) error
	Name() string
	IsEnabled() bool
}

type SentryHook

type SentryHook struct {
	LogLevels []log.Level
}

func NewSentryHook

func NewSentryHook(levels []log.Level) *SentryHook

func (*SentryHook) Fire

func (s *SentryHook) Fire(entry *log.Entry) error

func (*SentryHook) Levels

func (s *SentryHook) Levels() []log.Level

type TaskName

type TaskName string

const (
	EventProcessor      TaskName = "EventProcessor"
	DeadLetterProcessor TaskName = "DeadLetterProcessor"
)

func (TaskName) SetPrefix

func (t TaskName) SetPrefix(prefix string) TaskName