vikunja/vikunja
5
48
Fork 86
Code Issues 150 Pull Requests 36 Packages Releases 37 Activity

feat: webhooks (#1624)
Some checks failed
continuous-integration/drone/push Build is failing
Details

Browse Source 
Reviewed-on: vikunja/api#1624
This commit is contained in:
konrad 2023-10-20 11:06:36 +00:00
commit 4d9baa38d0
18 changed files with 1605 additions and 82 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
config.yml.sample
View File

@ -346,3 +346,13 @@ defaultsettings:
language: <unset>
# The time zone of each individual user. This will affect when users get reminders and overdue task emails.
timezone: <time zone set at service.timezone>
webhooks:
# Whether to enable support for webhooks
enabled: true
# The timout in seconds until a webhook request fails when no response has been received.
timoutseconds: 30
# The URL of [a mole instance](https://github.com/frain-dev/mole) to use to proxy outgoing webhook requests. You should use this and configure appropriately if you're not the only one using your Vikunja instance. More info about why: https://webhooks.fyi/best-practices/webhook-providers#implement-security-on-egress-communication. Must be used in combination with `webhooks.password` (see below).
proxyurl:
# The proxy password to use when authenticating against the proxy.
proxypassword:

50
docs/content/doc/setup/config.md
View File

@ -1327,3 +1327,53 @@ Full path: `defaultsettings.timezone`
Environment path: `VIKUNJA_DEFAULTSETTINGS_TIMEZONE`
---
## webhooks
### enabled
Whether to enable support for webhooks
Default: `true`
Full path: `webhooks.enabled`
Environment path: `VIKUNJA_WEBHOOKS_ENABLED`
### timoutseconds
The timout in seconds until a webhook request fails when no response has been received.
Default: `30`
Full path: `webhooks.timoutseconds`
Environment path: `VIKUNJA_WEBHOOKS_TIMOUTSECONDS`
### proxyurl
The URL of [a mole instance](https://github.com/frain-dev/mole) to use to proxy outgoing webhook requests. You should use this and configure appropriately if you're not the only one using your Vikunja instance. More info about why: https://webhooks.fyi/best-practices/webhook-providers#implement-security-on-egress-communication. Must be used in combination with `webhooks.password` (see below).
Default: `<empty>`
Full path: `webhooks.proxyurl`
Environment path: `VIKUNJA_WEBHOOKS_PROXYURL`
### proxypassword
The proxy password to use when authenticating against the proxy.
Default: `<empty>`
Full path: `webhooks.proxypassword`
Environment path: `VIKUNJA_WEBHOOKS_PROXYPASSWORD`

58
docs/content/doc/usage/webhooks.md Normal file
View File

@ -0,0 +1,58 @@
---
title: "Webhooks"
date: 2023-10-17T19:51:32+02:00
draft: false
type: doc
menu:
sidebar:
parent: "usage"
---
# Webhooks
Starting with version 0.22.0, Vikunja allows you to define webhooks to notify other services of events happening within Vikunja.
{{< table_of_contents >}}
## How to create webhooks
To create a webhook, in the project options select "Webhooks". The form will allow you to create and modify webhooks.
Check out [the api docs](https://try.vikunja.io/api/v1/docs#tag/webhooks) for information about how to create webhooks programatically.
## Available events and their payload
All events registered as webhook events in [the event listeners definition](https://kolaente.dev/vikunja/api/src/branch/main/pkg/models/listeners.go#L69) can be used as webhook target.
A webhook payload will look similar to this:
```json
{
"event_name": "task.created",
"time": "2023-10-17T19:39:32.924194436+02:00",
"data": {}
}
```
The `data` property will contain the raw event data as it was registered in the `listeners.go` file.
The `time` property holds the time when the webhook payload data was sent.
It always uses the ISO 8601 format with date, time and time zone offset.
## Security considerations
### Signing
Vikunja allows you to provide a secret when creating the webhook.
If you set a secret, all outgoing webhook requests will contain an `X-Vikunja-Signature` header with an HMAC signature over the webhook json payload.
Check out [webhooks.fyi](https://webhooks.fyi/security/hmac) for more information about how to validate the HMAC signature.
### Hosting webhook infrastructure
Vikunja has support to use [mole](https://github.com/frain-dev/mole) as a proxy for outgoing webhook requests.
This allows you to prevent SSRF attacts on your own infrastructure.
You should use this and [configure it appropriately]({{< ref "../setup/config.md">}}#webhooks) if you're not the only one using your Vikunja instance.
Check out [webhooks.fyi](https://webhooks.fyi/best-practices/webhook-providers#implement-security-on-egress-communication) for more information about the attack vector and reasoning to prevent this.

8
pkg/config/config.go
View File

@ -172,6 +172,11 @@ const (
DefaultSettingsLanguage Key = `defaultsettings.language`
DefaultSettingsTimezone Key = `defaultsettings.timezone`
DefaultSettingsOverdueTaskRemindersTime Key = `defaultsettings.overdue_tasks_reminders_time`
WebhooksEnabled Key = `webhooks.enabled`
WebhooksTimeoutSeconds Key = `webhooks.timeoutseconds`
WebhooksProxyURL Key = `webhooks.proxyurl`
WebhooksProxyPassword Key = `webhooks.proxypassword`
)
// GetString returns a string config value
@ -387,6 +392,9 @@ func InitDefaultConfig() {
DefaultSettingsAvatarProvider.setDefault("initials")
DefaultSettingsOverdueTaskRemindersEnabled.setDefault(true)
DefaultSettingsOverdueTaskRemindersTime.setDefault("9:00")
// Webhook
WebhooksEnabled.setDefault(true)
WebhooksTimeoutSeconds.setDefault(30)
}
// InitConfig initializes the config, sets defaults etc.

52
pkg/migration/20230913202615.go Normal file
View File

@ -0,0 +1,52 @@
// Vikunja is a to-do list application to facilitate your life.
// Copyright 2018-present Vikunja and contributors. All rights reserved.
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public Licensee as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU Affero General Public Licensee for more details.
//
// You should have received a copy of the GNU Affero General Public Licensee
// along with this program. If not, see <https://www.gnu.org/licenses/>.
package migration
import (
"time"
"src.techknowlogick.com/xormigrate"
"xorm.io/xorm"
)
type webhooks20230913202615 struct {
ID int64 `xorm:"bigint autoincr not null unique pk" json:"id" param:"webhook"`
TargetURL string `xorm:"not null" valid:"minstringlength(1)" minLength:"1" json:"target_url"`
Events []string `xorm:"JSON not null" valid:"minstringlength(1)" minLength:"1" json:"event"`
ProjectID int64 `xorm:"bigint not null index" json:"project_id" param:"project"`
Secret string `xorm:"null" json:"secret"`
CreatedByID int64 `xorm:"bigint not null" json:"-"`
Created time.Time `xorm:"created not null" json:"created"`
Updated time.Time `xorm:"updated not null" json:"updated"`
}
func (webhooks20230913202615) TableName() string {
return "webhooks"
}
func init() {
migrations = append(migrations, &xormigrate.Migration{
ID: "20230913202615",
Description: "",
Migrate: func(tx *xorm.Engine) error {
return tx.Sync2(webhooks20230913202615{})
},
Rollback: func(tx *xorm.Engine) error {
return nil
},
})
}

6
pkg/models/api_tokens.go
View File

@ -122,9 +122,9 @@ func HashToken(token, salt string) string {
// @Accept json
// @Produce json
// @Security JWTKeyAuth
// @Param page query int false "The page number for tasks. Used for pagination. If not provided, the first page of results is returned."
// @Param per_page query int false "The maximum number of tasks per bucket per page. This parameter is limited by the configured maximum of items per page."
// @Param s query string false "Search tasks by task text."
// @Param page query int false "The page number, used for pagination. If not provided, the first page of results is returned."
// @Param per_page query int false "The maximum number of tokens per page. This parameter is limited by the configured maximum of items per page."
// @Param s query string false "Search tokens by their title."
// @Success 200 {array} models.APIToken "The list of all tokens"
// @Failure 500 {object} models.Message "Internal server error"
// @Router /tokens [get]

11
pkg/models/error.go
View File

@ -110,6 +110,17 @@ func (err ValidationHTTPError) Error() string {
return theErr.Error()
}
func InvalidFieldError(fields []string) error {
return ValidationHTTPError{
HTTPError: web.HTTPError{
HTTPCode: http.StatusPreconditionFailed,
Code: ErrCodeInvalidData,
Message: "Invalid Data",
},
InvalidFields: fields,
}
}
// ===========
// Project errors
// ===========

114
pkg/models/events.go
View File

@ -27,8 +27,8 @@ import (
// TaskCreatedEvent represents an event where a task has been created
type TaskCreatedEvent struct {
Task *Task
Doer *user.User
Task *Task `json:"task"`
Doer *user.User `json:"doer"`
}
// Name defines the name for TaskCreatedEvent
@ -38,8 +38,8 @@ func (t *TaskCreatedEvent) Name() string {
// TaskUpdatedEvent represents an event where a task has been updated
type TaskUpdatedEvent struct {
Task *Task
Doer *user.User
Task *Task `json:"task"`
Doer *user.User `json:"doer"`
}
// Name defines the name for TaskUpdatedEvent
@ -49,8 +49,8 @@ func (t *TaskUpdatedEvent) Name() string {
// TaskDeletedEvent represents a TaskDeletedEvent event
type TaskDeletedEvent struct {
Task *Task
Doer *user.User
Task *Task `json:"task"`
Doer *user.User `json:"doer"`
}
// Name defines the name for TaskDeletedEvent
@ -60,9 +60,9 @@ func (t *TaskDeletedEvent) Name() string {
// TaskAssigneeCreatedEvent represents an event where a task has been assigned to a user
type TaskAssigneeCreatedEvent struct {
Task *Task
Assignee *user.User
Doer *user.User
Task *Task `json:"task"`
Assignee *user.User `json:"assignee"`
Doer *user.User `json:"doer"`
}
// Name defines the name for TaskAssigneeCreatedEvent
@ -72,9 +72,9 @@ func (t *TaskAssigneeCreatedEvent) Name() string {
// TaskAssigneeDeletedEvent represents a TaskAssigneeDeletedEvent event
type TaskAssigneeDeletedEvent struct {
Task *Task
Assignee *user.User
Doer *user.User
Task *Task `json:"task"`
Assignee *user.User `json:"assignee"`
Doer *user.User `json:"doer"`
}
// Name defines the name for TaskAssigneeDeletedEvent
@ -84,9 +84,9 @@ func (t *TaskAssigneeDeletedEvent) Name() string {
// TaskCommentCreatedEvent represents an event where a task comment has been created
type TaskCommentCreatedEvent struct {
Task *Task
Comment *TaskComment
Doer *user.User
Task *Task `json:"task"`
Comment *TaskComment `json:"comment"`
Doer *user.User `json:"doer"`
}
// Name defines the name for TaskCommentCreatedEvent
@ -96,9 +96,9 @@ func (t *TaskCommentCreatedEvent) Name() string {
// TaskCommentUpdatedEvent represents a TaskCommentUpdatedEvent event
type TaskCommentUpdatedEvent struct {
Task *Task
Comment *TaskComment
Doer *user.User
Task *Task `json:"task"`
Comment *TaskComment `json:"comment"`
Doer *user.User `json:"doer"`
}
// Name defines the name for TaskCommentUpdatedEvent
@ -108,9 +108,9 @@ func (t *TaskCommentUpdatedEvent) Name() string {
// TaskCommentDeletedEvent represents a TaskCommentDeletedEvent event
type TaskCommentDeletedEvent struct {
Task *Task
Comment *TaskComment
Doer *user.User
Task *Task `json:"task"`
Comment *TaskComment `json:"comment"`
Doer *user.User `json:"doer"`
}
// Name defines the name for TaskCommentDeletedEvent
@ -120,9 +120,9 @@ func (t *TaskCommentDeletedEvent) Name() string {
// TaskAttachmentCreatedEvent represents a TaskAttachmentCreatedEvent event
type TaskAttachmentCreatedEvent struct {
Task *Task
Attachment *TaskAttachment
Doer *user.User
Task *Task `json:"task"`
Attachment *TaskAttachment `json:"attachment"`
Doer *user.User `json:"doer"`
}
// Name defines the name for TaskAttachmentCreatedEvent
@ -132,9 +132,9 @@ func (t *TaskAttachmentCreatedEvent) Name() string {
// TaskAttachmentDeletedEvent represents a TaskAttachmentDeletedEvent event
type TaskAttachmentDeletedEvent struct {
Task *Task
Attachment *TaskAttachment
Doer *user.User
Task *Task `json:"task"`
Attachment *TaskAttachment `json:"attachment"`
Doer *user.User `json:"doer"`
}
// Name defines the name for TaskAttachmentDeletedEvent
@ -144,9 +144,9 @@ func (t *TaskAttachmentDeletedEvent) Name() string {
// TaskRelationCreatedEvent represents a TaskRelationCreatedEvent event
type TaskRelationCreatedEvent struct {
Task *Task
Relation *TaskRelation
Doer *user.User
Task *Task `json:"task"`
Relation *TaskRelation `json:"relation"`
Doer *user.User `json:"doer"`
}
// Name defines the name for TaskRelationCreatedEvent
@ -156,9 +156,9 @@ func (t *TaskRelationCreatedEvent) Name() string {
// TaskRelationDeletedEvent represents a TaskRelationDeletedEvent event
type TaskRelationDeletedEvent struct {
Task *Task
Relation *TaskRelation
Doer *user.User
Task *Task `json:"task"`
Relation *TaskRelation `json:"relation"`
Doer *user.User `json:"doer"`
}
// Name defines the name for TaskRelationDeletedEvent
@ -172,8 +172,8 @@ func (t *TaskRelationDeletedEvent) Name() string {
// ProjectCreatedEvent represents an event where a project has been created
type ProjectCreatedEvent struct {
Project *Project
Doer *user.User
Project *Project `json:"project"`
Doer *user.User `json:"doer"`
}
// Name defines the name for ProjectCreatedEvent
@ -183,23 +183,23 @@ func (l *ProjectCreatedEvent) Name() string {
// ProjectUpdatedEvent represents an event where a project has been updated
type ProjectUpdatedEvent struct {
Project *Project
Doer web.Auth
Project *Project `json:"project"`
Doer web.Auth `json:"doer"`
}
// Name defines the name for ProjectUpdatedEvent
func (l *ProjectUpdatedEvent) Name() string {
func (p *ProjectUpdatedEvent) Name() string {
return "project.updated"
}
// ProjectDeletedEvent represents an event where a project has been deleted
type ProjectDeletedEvent struct {
Project *Project
Doer web.Auth
Project *Project `json:"project"`
Doer web.Auth `json:"doer"`
}
// Name defines the name for ProjectDeletedEvent
func (t *ProjectDeletedEvent) Name() string {
func (p *ProjectDeletedEvent) Name() string {
return "project.deleted"
}
@ -209,25 +209,25 @@ func (t *ProjectDeletedEvent) Name() string {
// ProjectSharedWithUserEvent represents an event where a project has been shared with a user
type ProjectSharedWithUserEvent struct {
Project *Project
User *user.User
Doer web.Auth
Project *Project `json:"project"`
User *user.User `json:"user"`
Doer web.Auth `json:"doer"`
}
// Name defines the name for ProjectSharedWithUserEvent
func (l *ProjectSharedWithUserEvent) Name() string {
func (p *ProjectSharedWithUserEvent) Name() string {
return "project.shared.user"
}
// ProjectSharedWithTeamEvent represents an event where a project has been shared with a team
type ProjectSharedWithTeamEvent struct {
Project *Project
Team *Team
Doer web.Auth
Project *Project `json:"project"`
Team *Team `json:"team"`
Doer web.Auth `json:"doer"`
}
// Name defines the name for ProjectSharedWithTeamEvent
func (l *ProjectSharedWithTeamEvent) Name() string {
func (p *ProjectSharedWithTeamEvent) Name() string {
return "project.shared.team"
}
@ -237,9 +237,9 @@ func (l *ProjectSharedWithTeamEvent) Name() string {
// TeamMemberAddedEvent defines an event where a user is added to a team
type TeamMemberAddedEvent struct {
Team *Team
Member *user.User
Doer *user.User
Team *Team `json:"team"`
Member *user.User `json:"member"`
Doer *user.User `json:"doer"`
}
// Name defines the name for TeamMemberAddedEvent
@ -249,8 +249,8 @@ func (t *TeamMemberAddedEvent) Name() string {
// TeamCreatedEvent represents a TeamCreatedEvent event
type TeamCreatedEvent struct {
Team *Team
Doer web.Auth
Team *Team `json:"team"`
Doer web.Auth `json:"doer"`
}
// Name defines the name for TeamCreatedEvent
@ -260,8 +260,8 @@ func (t *TeamCreatedEvent) Name() string {
// TeamDeletedEvent represents a TeamDeletedEvent event
type TeamDeletedEvent struct {
Team *Team
Doer web.Auth
Team *Team `json:"team"`
Doer web.Auth `json:"doer"`
}
// Name defines the name for TeamDeletedEvent
@ -271,7 +271,7 @@ func (t *TeamDeletedEvent) Name() string {
// UserDataExportRequestedEvent represents a UserDataExportRequestedEvent event
type UserDataExportRequestedEvent struct {
User *user.User
User *user.User `json:"user"`
}
// Name defines the name for UserDataExportRequestedEvent

113
pkg/models/listeners.go
View File

@ -19,6 +19,7 @@ package models
import (
"encoding/json"
"strconv"
"time"
"code.vikunja.io/api/pkg/config"
@ -65,6 +66,24 @@ func RegisterListeners() {
events.RegisterListener((&TaskDeletedEvent{}).Name(), &RemoveTaskFromTypesense{})
events.RegisterListener((&TaskCreatedEvent{}).Name(), &AddTaskToTypesense{})
}
if config.WebhooksEnabled.GetBool() {
RegisterEventForWebhook(&TaskCreatedEvent{})
RegisterEventForWebhook(&TaskUpdatedEvent{})
RegisterEventForWebhook(&TaskDeletedEvent{})
RegisterEventForWebhook(&TaskAssigneeCreatedEvent{})
RegisterEventForWebhook(&TaskAssigneeDeletedEvent{})
RegisterEventForWebhook(&TaskCommentCreatedEvent{})
RegisterEventForWebhook(&TaskCommentUpdatedEvent{})
RegisterEventForWebhook(&TaskCommentDeletedEvent{})
RegisterEventForWebhook(&TaskAttachmentCreatedEvent{})
RegisterEventForWebhook(&TaskAttachmentDeletedEvent{})
RegisterEventForWebhook(&TaskRelationCreatedEvent{})
RegisterEventForWebhook(&TaskRelationDeletedEvent{})
RegisterEventForWebhook(&ProjectUpdatedEvent{})
RegisterEventForWebhook(&ProjectDeletedEvent{})
RegisterEventForWebhook(&ProjectSharedWithUserEvent{})
RegisterEventForWebhook(&ProjectSharedWithTeamEvent{})
}
}
//////
@ -609,6 +628,100 @@ func (s *SendProjectCreatedNotification) Handle(msg *message.Message) (err error
return nil
}
// WebhookListener represents a listener
type WebhookListener struct {
EventName string
}
// Name defines the name for the WebhookListener listener
func (wl *WebhookListener) Name() string {
return "webhook.listener"
}
type WebhookPayload struct {
EventName string `json:"event_name"`
Time time.Time `json:"time"`
Data interface{} `json:"data"`
}
func getProjectIDFromAnyEvent(eventPayload map[string]interface{}) int64 {
if task, has := eventPayload["task"]; has {
t := task.(map[string]interface{})
if projectID, has := t["project_id"]; has {
switch v := projectID.(type) {
case int64:
return v
case float64:
return int64(v)
}
return projectID.(int64)
}
}
if project, has := eventPayload["project"]; has {
t := project.(map[string]interface{})
if projectID, has := t["id"]; has {
switch v := projectID.(type) {
case int64:
return v
case float64:
return int64(v)
}
return projectID.(int64)
}
}
return 0
}
// Handle is executed when the event WebhookListener listens on is fired
func (wl *WebhookListener) Handle(msg *message.Message) (err error) {
var event map[string]interface{}
err = json.Unmarshal(msg.Payload, &event)
if err != nil {
return err
}
projectID := getProjectIDFromAnyEvent(event)
if projectID == 0 {
log.Debugf("event %s does not contain a project id, not handling webhook", wl.EventName)
return nil
}
s := db.NewSession()
defer s.Close()
ws := []*Webhook{}
err = s.Where("project_id = ?", projectID).
Find(&ws)
if err != nil {
return err
}
var webhook *Webhook
for _, w := range ws {
for _, e := range w.Events {
if e == wl.EventName {
webhook = w
break
}
}
}
if webhook == nil {
log.Debugf("Did not find any webhook for the %s event for project %d, not sending", wl.EventName, projectID)
return nil
}
err = webhook.sendWebhookPayload(&WebhookPayload{
EventName: wl.EventName,
Time: time.Now(),
Data: event,
})
return
}
///////
// Team Events

298
pkg/models/webhooks.go Normal file
View File

@ -0,0 +1,298 @@
// Vikunja is a to-do list application to facilitate your life.
// Copyright 2018-present Vikunja and contributors. All rights reserved.
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public Licensee as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU Affero General Public Licensee for more details.
//
// You should have received a copy of the GNU Affero General Public Licensee
// along with this program. If not, see <https://www.gnu.org/licenses/>.
package models
import (
"bytes"
"context"
"crypto/hmac"
"crypto/sha256"
"encoding/base64"
"encoding/hex"
"encoding/json"
"net/http"
"net/url"
"sort"
"strings"
"sync"
"time"
"code.vikunja.io/api/pkg/config"
"code.vikunja.io/api/pkg/events"
"code.vikunja.io/api/pkg/log"
"code.vikunja.io/api/pkg/user"
"code.vikunja.io/api/pkg/version"
"code.vikunja.io/web"
"xorm.io/xorm"
)
var webhookClient *http.Client
type Webhook struct {
// The generated ID of this webhook target
ID int64 `xorm:"bigint autoincr not null unique pk" json:"id" param:"webhook"`
// The target URL where the POST request with the webhook payload will be made
TargetURL string `xorm:"not null" valid:"required,url" json:"target_url"`
// The webhook events which should fire this webhook target
Events []string `xorm:"JSON not null" valid:"required" json:"events"`
// The project ID of the project this webhook target belongs to
ProjectID int64 `xorm:"bigint not null index" json:"project_id" param:"project"`
// If provided, webhook requests will be signed using HMAC. Check out the docs about how to use this: https://vikunja.io/docs/webhooks/#signing
Secret string `xorm:"null" json:"secret"`
// The user who initially created the webhook target.
CreatedBy *user.User `xorm:"-" json:"created_by" valid:"-"`
CreatedByID int64 `xorm:"bigint not null" json:"-"`
// A timestamp when this webhook target was created. You cannot change this value.
Created time.Time `xorm:"created not null" json:"created"`
// A timestamp when this webhook target was last updated. You cannot change this value.
Updated time.Time `xorm:"updated not null" json:"updated"`
web.CRUDable `xorm:"-" json:"-"`
web.Rights `xorm:"-" json:"-"`
}
func (w *Webhook) TableName() string {
return "webhooks"
}
var availableWebhookEvents map[string]bool
var availableWebhookEventsLock *sync.Mutex
func init() {
availableWebhookEvents = make(map[string]bool)
availableWebhookEventsLock = &sync.Mutex{}
}
func RegisterEventForWebhook(event events.Event) {
availableWebhookEventsLock.Lock()
defer availableWebhookEventsLock.Unlock()
availableWebhookEvents[event.Name()] = true
events.RegisterListener(event.Name(), &WebhookListener{
EventName: event.Name(),
})
}
func GetAvailableWebhookEvents() []string {
evts := []string{}
for e := range availableWebhookEvents {
evts = append(evts, e)
}
sort.Strings(evts)
return evts
}
// Create creates a webhook target
// @Summary Create a webhook target
// @Description Create a webhook target which receives POST requests about specified events from a project.
// @tags webhooks
// @Accept json
// @Produce json
// @Security JWTKeyAuth
// @Param id path int true "Project ID"
// @Param webhook body models.Webhook true "The webhook target object with required fields"
// @Success 200 {object} models.Webhook "The created webhook target."
// @Failure 400 {object} web.HTTPError "Invalid webhook object provided."
// @Failure 500 {object} models.Message "Internal error"
// @Router /projects/{id}/webhooks [put]
func (w *Webhook) Create(s *xorm.Session, a web.Auth) (err error) {
if !strings.HasPrefix(w.TargetURL, "http") {
return InvalidFieldError([]string{"target_url"})
}
for _, event := range w.Events {
if _, has := availableWebhookEvents[event]; !has {
return InvalidFieldError([]string{"events"})
}
}
w.CreatedByID = a.GetID()
_, err = s.Insert(w)
if err != nil {
return err
}
w.CreatedBy, err = user.GetUserByID(s, a.GetID())
return
}
// ReadAll returns all webhook targets for a project
// @Summary Get all api webhook targets for the specified project
// @Description Get all api webhook targets for the specified project.
// @tags webhooks
// @Accept json
// @Produce json
// @Security JWTKeyAuth
// @Param page query int false "The page number. Used for pagination. If not provided, the first page of results is returned."
// @Param per_page query int false "The maximum number of items per bucket per page. This parameter is limited by the configured maximum of items per page."
// @Param id path int true "Project ID"
// @Success 200 {array} models.Webhook "The list of all webhook targets"
// @Failure 500 {object} models.Message "Internal server error"
// @Router /projects/{id}/webhooks [get]
func (w *Webhook) ReadAll(s *xorm.Session, a web.Auth, _ string, page int, perPage int) (result interface{}, resultCount int, numberOfTotalItems int64, err error) {
p := &Project{ID: w.ProjectID}
can, _, err := p.CanRead(s, a)
if err != nil {
return nil, 0, 0, err
}
if !can {
return nil, 0, 0, ErrGenericForbidden{}
}
ws := []*Webhook{}
err = s.Where("project_id = ?", w.ProjectID).
Limit(getLimitFromPageIndex(page, perPage)).
Find(&ws)
if err != nil {
return
}
total, err := s.Where("project_id = ?", w.ProjectID).
Count(&Webhook{})
if err != nil {
return
}
userIDs := []int64{}
for _, webhook := range ws {
userIDs = append(userIDs, webhook.CreatedByID)
}
users, err := user.GetUsersByIDs(s, userIDs)
if err != nil {
return nil, 0, 0, err
}
for _, webhook := range ws {
webhook.Secret = ""
webhook.CreatedBy = users[webhook.CreatedByID]
}
return ws, len(ws), total, err
}
// Update updates a webhook target
// @Summary Change a webhook target's events.
// @Description Change a webhook target's events. You cannot change other values of a webhook.
// @tags webhooks
// @Accept json
// @Produce json
// @Security JWTKeyAuth
// @Param id path int true "Project ID"
// @Param webhookID path int true "Webhook ID"
// @Success 200 {object} models.Webhook "Updated webhook target"
// @Failure 404 {object} web.HTTPError "The webhok target does not exist"
// @Failure 500 {object} models.Message "Internal error"
// @Router /projects/{id}/webhooks/{webhookID} [post]
func (w *Webhook) Update(s *xorm.Session, _ web.Auth) (err error) {
for _, event := range w.Events {
if _, has := availableWebhookEvents[event]; !has {
return InvalidFieldError([]string{"events"})
}
}
_, err = s.Where("id = ?", w.ID).
Cols("events").
Update(w)
return
}
// Delete deletes a webhook target
// @Summary Deletes an existing webhook target
// @Description Delete any of the project's webhook targets.
// @tags webhooks
// @Accept json
// @Produce json
// @Security JWTKeyAuth
// @Param id path int true "Project ID"
// @Param webhookID path int true "Webhook ID"
// @Success 200 {object} models.Message "Successfully deleted."
// @Failure 404 {object} web.HTTPError "The webhok target does not exist."
// @Failure 500 {object} models.Message "Internal error"
// @Router /projects/{id}/webhooks/{webhookID} [delete]
func (w *Webhook) Delete(s *xorm.Session, _ web.Auth) (err error) {
_, err = s.Where("id = ?", w.ID).Delete(&Webhook{})
return
}
func getWebhookHTTPClient() (client *http.Client) {
if webhookClient != nil {
return webhookClient
}
client = http.DefaultClient
client.Timeout = time.Duration(config.WebhooksTimeoutSeconds.GetInt()) * time.Second
if config.WebhooksProxyURL.GetString() == "" || config.WebhooksProxyPassword.GetString() == "" {
webhookClient = client
return
}
proxyURL, _ := url.Parse(config.WebhooksProxyURL.GetString())
client.Transport = &http.Transport{
Proxy: http.ProxyURL(proxyURL),
ProxyConnectHeader: http.Header{
"Proxy-Authorization": []string{"Basic " + base64.StdEncoding.EncodeToString([]byte("vikunja:"+config.WebhooksProxyPassword.GetString()))},
"User-Agent": []string{"Vikunja/" + version.Version},
},
}
webhookClient = client
return
}
func (w *Webhook) sendWebhookPayload(p *WebhookPayload) (err error) {
payload, err := json.Marshal(p)
if err != nil {
return err
}
req, err := http.NewRequestWithContext(context.Background(), http.MethodPost, w.TargetURL, bytes.NewReader(payload))
if err != nil {
return err
}
if len(w.Secret) > 0 {
sig256 := hmac.New(sha256.New, []byte(w.Secret))
_, err = sig256.Write(payload)
if err != nil {
log.Errorf("Could not generate webhook signature for Webhook %d: %s", w.ID, err)
}
signature := hex.EncodeToString(sig256.Sum(nil))
req.Header.Add("X-Vikunja-Signature", signature)
}
req.Header.Add("User-Agent", "Vikunja/"+version.Version)
client := getWebhookHTTPClient()
res, err := client.Do(req)
if err != nil {
return err
}
defer res.Body.Close()
log.Debugf("Sent webhook payload for webhook %d for event %s", w.ID, p.EventName)
return
}

49
pkg/models/webhooks_rights.go Normal file
View File

@ -0,0 +1,49 @@
// Vikunja is a to-do list application to facilitate your life.
// Copyright 2018-present Vikunja and contributors. All rights reserved.
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public Licensee as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU Affero General Public Licensee for more details.
//
// You should have received a copy of the GNU Affero General Public Licensee
// along with this program. If not, see <https://www.gnu.org/licenses/>.
package models
import (
"code.vikunja.io/web"
"xorm.io/xorm"
)
func (w *Webhook) CanRead(s *xorm.Session, a web.Auth) (bool, int, error) {
p := &Project{ID: w.ProjectID}
return p.CanRead(s, a)
}
func (w *Webhook) CanDelete(s *xorm.Session, a web.Auth) (bool, error) {
return w.canDoWebhook(s, a)
}
func (w *Webhook) CanUpdate(s *xorm.Session, a web.Auth) (bool, error) {
return w.canDoWebhook(s, a)
}
func (w *Webhook) CanCreate(s *xorm.Session, a web.Auth) (bool, error) {
return w.canDoWebhook(s, a)
}
func (w *Webhook) canDoWebhook(s *xorm.Session, a web.Auth) (bool, error) {
_, isShareAuth := a.(*LinkSharing)
if isShareAuth {
return false, nil
}
p := &Project{ID: w.ProjectID}
return p.CanUpdate(s, a)
}

2
pkg/routes/api/v1/info.go
View File

@ -50,6 +50,7 @@ type vikunjaInfos struct {
UserDeletionEnabled bool `json:"user_deletion_enabled"`
TaskCommentsEnabled bool `json:"task_comments_enabled"`
DemoModeEnabled bool `json:"demo_mode_enabled"`
WebhooksEnabled bool `json:"webhooks_enabled"`
}
type authInfo struct {
@ -94,6 +95,7 @@ func Info(c echo.Context) error {
UserDeletionEnabled: config.ServiceEnableUserDeletion.GetBool(),
TaskCommentsEnabled: config.ServiceEnableTaskComments.GetBool(),
DemoModeEnabled: config.ServiceDemoMode.GetBool(),
WebhooksEnabled: config.WebhooksEnabled.GetBool(),
AvailableMigrators: []string{
(&vikunja_file.FileMigrator{}).Name(),
(&ticktick.Migrator{}).Name(),

38
pkg/routes/api/v1/webhooks.go Normal file
View File

@ -0,0 +1,38 @@
// Vikunja is a to-do list application to facilitate your life.
// Copyright 2018-present Vikunja and contributors. All rights reserved.
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public Licensee as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU Affero General Public Licensee for more details.
//
// You should have received a copy of the GNU Affero General Public Licensee
// along with this program. If not, see <https://www.gnu.org/licenses/>.
package v1
import (
"net/http"
"code.vikunja.io/api/pkg/models"
"github.com/labstack/echo/v4"
)
// GetAvailableWebhookEvents returns a list of all possible webhook target events
// @Summary Get all possible webhook events
// @Description Get all possible webhook events to use when creating or updating a webhook target.
// @tags webhooks
// @Accept json
// @Produce json
// @Security JWTKeyAuth
// @Success 200 {array} string "The list of all possible webhook events"
// @Failure 500 {object} models.Message "Internal server error"
// @Router /webhooks/events [get]
func GetAvailableWebhookEvents(c echo.Context) error {
return c.JSON(http.StatusOK, models.GetAvailableWebhookEvents())
}

14
pkg/routes/routes.go
View File

@ -574,6 +574,20 @@ func registerAPIRoutes(a *echo.Group) {
a.GET("/tokens", apiTokenProvider.ReadAllWeb)
a.PUT("/tokens", apiTokenProvider.CreateWeb)
a.DELETE("/tokens/:token", apiTokenProvider.DeleteWeb)
// Webhooks
if config.WebhooksEnabled.GetBool() {
webhookProvider := &handler.WebHandler{
EmptyStruct: func() handler.CObject {
return &models.Webhook{}
},
}
a.GET("/projects/:project/webhooks", webhookProvider.ReadAllWeb)
a.PUT("/projects/:project/webhooks", webhookProvider.CreateWeb)
a.DELETE("/projects/:project/webhooks/:webhook", webhookProvider.DeleteWeb)
a.POST("/projects/:project/webhooks/:webhook", webhookProvider.UpdateWeb)
a.GET("/webhooks/events", apiv1.GetAvailableWebhookEvents)
}
}
func registerMigrations(m *echo.Group) {

12
pkg/routes/validation.go
View File

@ -17,11 +17,8 @@
package routes
import (
"net/http"
"code.vikunja.io/api/pkg/models"
"code.vikunja.io/web"
"github.com/asaskevich/govalidator"
)
@ -43,14 +40,7 @@ func (cv *CustomValidator) Validate(i interface{}) error {
errs = append(errs, field+": "+e)
}
return models.ValidationHTTPError{
HTTPError: web.HTTPError{
HTTPCode: http.StatusPreconditionFailed,
Code: models.ErrCodeInvalidData,
Message: "Invalid Data",
},
InvalidFields: errs,
}
return models.InvalidFieldError(errs)
}
return nil
}

316
pkg/swagger/docs.go
View File

@ -2425,6 +2425,230 @@ const docTemplate = `{
}
}
},
"/projects/{id}/webhooks": {
"get": {
"security": [
{
"JWTKeyAuth": []
}
],
"description": "Get all api webhook targets for the specified project.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"webhooks"
],
"summary": "Get all api webhook targets for the specified project",
"parameters": [
{
"type": "integer",
"description": "The page number. Used for pagination. If not provided, the first page of results is returned.",
"name": "page",
"in": "query"
},
{
"type": "integer",
"description": "The maximum number of items per bucket per page. This parameter is limited by the configured maximum of items per page.",
"name": "per_page",
"in": "query"
},
{
"type": "integer",
"description": "Project ID",
"name": "id",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "The list of all webhook targets",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/models.Webhook"
}
}
},
"500": {
"description": "Internal server error",
"schema": {
"$ref": "#/definitions/models.Message"
}
}
}
},
"put": {
"security": [
{
"JWTKeyAuth": []
}
],
"description": "Create a webhook target which recieves POST requests about specified events from a project.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"webhooks"
],
"summary": "Create a webhook target",
"parameters": [
{
"type": "integer",
"description": "Project ID",
"name": "id",
"in": "path",
"required": true
},
{
"description": "The webhook target object with required fields",
"name": "webhook",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/models.Webhook"
}
}
],
"responses": {
"200": {
"description": "The created webhook target.",
"schema": {
"$ref": "#/definitions/models.Webhook"
}
},
"400": {
"description": "Invalid webhook object provided.",
"schema": {
"$ref": "#/definitions/web.HTTPError"
}
},
"500": {
"description": "Internal error",
"schema": {
"$ref": "#/definitions/models.Message"
}
}
}
}
},
"/projects/{id}/webhooks/{webhookID}": {
"post": {
"security": [
{
"JWTKeyAuth": []
}
],
"description": "Change a webhook target's events. You cannot change other values of a webhook.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"webhooks"
],
"summary": "Change a webhook target's events.",
"parameters": [
{
"type": "integer",
"description": "Project ID",
"name": "id",
"in": "path",
"required": true
},
{
"type": "integer",
"description": "Webhook ID",
"name": "webhookID",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "Updated webhook target",
"schema": {
"$ref": "#/definitions/models.Webhook"
}
},
"404": {
"description": "The webhok target does not exist",
"schema": {
"$ref": "#/definitions/web.HTTPError"
}
},
"500": {
"description": "Internal error",
"schema": {
"$ref": "#/definitions/models.Message"
}
}
}
},
"delete": {
"security": [
{
"JWTKeyAuth": []
}
],
"description": "Delete any of the project's webhook targets.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"webhooks"
],
"summary": "Deletes an existing webhook target",
"parameters": [
{
"type": "integer",
"description": "Project ID",
"name": "id",
"in": "path",
"required": true
},
{
"type": "integer",
"description": "Webhook ID",
"name": "webhookID",
"in": "path",
"required": true
}
],
"responses": {
"200": {
"description": "Successfully deleted.",
"schema": {
"$ref": "#/definitions/models.Message"
}
},
"404": {
"description": "The webhok target does not exist.",
"schema": {
"$ref": "#/definitions/web.HTTPError"
}
},
"500": {
"description": "Internal error",
"schema": {
"$ref": "#/definitions/models.Message"
}
}
}
}
},
"/projects/{projectID}/buckets/{bucketID}": {
"post": {
"security": [
@ -5427,19 +5651,19 @@ const docTemplate = `{
"parameters": [
{
"type": "integer",
"description": "The page number for tasks. Used for pagination. If not provided, the first page of results is returned.",
"description": "The page number, used for pagination. If not provided, the first page of results is returned.",
"name": "page",
"in": "query"
},
{
"type": "integer",
"description": "The maximum number of tasks per bucket per page. This parameter is limited by the configured maximum of items per page.",
"description": "The maximum number of tokens per page. This parameter is limited by the configured maximum of items per page.",
"name": "per_page",
"in": "query"
},
{
"type": "string",
"description": "Search tasks by task text.",
"description": "Search tokens by their title.",
"name": "s",
"in": "query"
}
@ -6783,6 +7007,43 @@ const docTemplate = `{
}
}
},
"/webhooks/events": {
"get": {
"security": [
{
"JWTKeyAuth": []
}
],
"description": "Get all possible webhook events to use when creating or updating a webhook target.",
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"tags": [
"webhooks"
],
"summary": "Get all possible webhook events",
"responses": {
"200": {
"description": "The list of all possible webhook events",
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
},
"500": {
"description": "Internal server error",
"schema": {
"$ref": "#/definitions/models.Message"
}
}
}
}
},
"/{username}/avatar": {
"get": {
"description": "Returns the user avatar as image.",
@ -8188,6 +8449,52 @@ const docTemplate = `{
}
}
},
"models.Webhook": {
"type": "object",
"properties": {
"created": {
"description": "A timestamp when this webhook target was created. You cannot change this value.",
"type": "string"
},
"created_by": {
"description": "The user who initially created the webhook target.",
"allOf": [
{
"$ref": "#/definitions/user.User"
}
]
},
"events": {
"description": "The webhook events which should fire this webhook target",
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"id": {
"description": "The generated ID of this webhook target",
"type": "integer"
},
"project_id": {
"description": "The project ID of the project this webhook target belongs to",
"type": "integer"
},
"secret": {
"description": "If provided, webhook requests will be signed using HMAC. Check out the docs about how to use this: https://vikunja.io/docs/webhooks/#signing",
"type": "string"
},
"target_url": {
"description": "The target URL where the POST request with the webhook payload will be made",
"type": "string",
"minLength": 1
},
"updated": {
"description": "A timestamp when this webhook target was last updated. You cannot change this value.",
"type": "string"
}
}
},
"notifications.DatabaseNotification": {
"type": "object",
"properties": {
@ -8618,6 +8925,9 @@ const docTemplate = `{