feat: webhooks (#1624)

Reviewed-on: https://kolaente.dev/vikunja/api/pulls/1624

config.yml.sample

@@ -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:

docs/content/doc/setup/config.md

@@ -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`
+
+

docs/content/doc/usage/webhooks.md

@@ -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.

pkg/config/config.go

@@ -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.

pkg/migration/20230913202615.go

@@ -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
+		},
+	})
+}

pkg/models/api_tokens.go

@@ -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 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 tasks per bucket per page. This parameter is limited by the configured maximum of items per page."
+// @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 tasks by task text."
+// @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]

pkg/models/error.go

@@ -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
 // ===========

pkg/models/events.go

@@ -27,8 +27,8 @@ import (
 
 // TaskCreatedEvent represents an event where a task has been created
 type TaskCreatedEvent struct {
-	Task *Task
+	Task *Task      `json:"task"`
-	Doer *user.User
+	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
+	Task *Task      `json:"task"`
-	Doer *user.User
+	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
+	Task *Task      `json:"task"`
-	Doer *user.User
+	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
+	Task     *Task      `json:"task"`
-	Assignee *user.User
+	Assignee *user.User `json:"assignee"`
-	Doer     *user.User
+	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
+	Task     *Task      `json:"task"`
-	Assignee *user.User
+	Assignee *user.User `json:"assignee"`
-	Doer     *user.User
+	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
+	Task    *Task        `json:"task"`
-	Comment *TaskComment
+	Comment *TaskComment `json:"comment"`
-	Doer    *user.User
+	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
+	Task    *Task        `json:"task"`
-	Comment *TaskComment
+	Comment *TaskComment `json:"comment"`
-	Doer    *user.User
+	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
+	Task    *Task        `json:"task"`
-	Comment *TaskComment
+	Comment *TaskComment `json:"comment"`
-	Doer    *user.User
+	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
+	Task       *Task           `json:"task"`
-	Attachment *TaskAttachment
+	Attachment *TaskAttachment `json:"attachment"`
-	Doer       *user.User
+	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
+	Task       *Task           `json:"task"`
-	Attachment *TaskAttachment
+	Attachment *TaskAttachment `json:"attachment"`
-	Doer       *user.User
+	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
+	Task     *Task         `json:"task"`
-	Relation *TaskRelation
+	Relation *TaskRelation `json:"relation"`
-	Doer     *user.User
+	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
+	Task     *Task         `json:"task"`
-	Relation *TaskRelation
+	Relation *TaskRelation `json:"relation"`
-	Doer     *user.User
+	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
+	Project *Project   `json:"project"`
-	Doer    *user.User
+	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
+	Project *Project `json:"project"`
-	Doer    web.Auth
+	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
+	Project *Project `json:"project"`
-	Doer    web.Auth
+	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
+	Project *Project   `json:"project"`
-	User    *user.User
+	User    *user.User `json:"user"`
-	Doer    web.Auth
+	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
+	Project *Project `json:"project"`
-	Team    *Team
+	Team    *Team    `json:"team"`
-	Doer    web.Auth
+	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
+	Team   *Team      `json:"team"`
-	Member *user.User
+	Member *user.User `json:"member"`
-	Doer   *user.User
+	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
+	Team *Team    `json:"team"`
-	Doer web.Auth
+	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
+	Team *Team    `json:"team"`
-	Doer web.Auth
+	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

pkg/models/listeners.go

@@ -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
 

pkg/models/webhooks.go

@@ -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
+}

pkg/models/webhooks_rights.go

@@ -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)
+}

pkg/routes/api/v1/info.go

@@ -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(),

pkg/routes/api/v1/webhooks.go

@@ -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())
+}

pkg/routes/routes.go

@@ -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) {

pkg/routes/validation.go

@@ -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{
+		return models.InvalidFieldError(errs)
-			HTTPError: web.HTTPError{
-				HTTPCode: http.StatusPreconditionFailed,
-				Code:     models.ErrCodeInvalidData,
-				Message:  "Invalid Data",
-			},
-			InvalidFields: errs,
-		}
 	}
 	return nil
 }

pkg/swagger/docs.go

@@ -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 = `{
                 },
                 "version": {
                     "type": "string"
+                },
+                "webhooks_enabled": {
+                    "type": "boolean"
                 }
             }
         },

pkg/swagger/swagger.json

@@ -2417,6 +2417,230 @@
                 }
             }
         },
+        "/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": [
@@ -5419,19 +5643,19 @@
                 "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"
                     }
@@ -6775,6 +6999,43 @@
                 }
             }
         },
+        "/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.",
@@ -8180,6 +8441,52 @@
                 }
             }
         },
+        "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": {
@@ -8610,6 +8917,9 @@
                 },
                 "version": {
                     "type": "string"
+                },
+                "webhooks_enabled": {
+                    "type": "boolean"
                 }
             }
         },

pkg/swagger/swagger.yaml

@@ -1040,6 +1040,42 @@ definitions:
         minLength: 1
         type: string
     type: object
+  models.Webhook:
+    properties:
+      created:
+        description: A timestamp when this webhook target was created. You cannot
+          change this value.
+        type: string
+      created_by:
+        allOf:
+        - $ref: '#/definitions/user.User'
+        description: The user who initially created the webhook target.
+      events:
+        description: The webhook events which should fire this webhook target
+        items:
+          minLength: 1
+          type: string
+        type: array
+      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
+        minLength: 1
+        type: string
+      updated:
+        description: A timestamp when this webhook target was last updated. You cannot
+          change this value.
+        type: string
+    type: object
   notifications.DatabaseNotification:
     properties:
       created:
@@ -1352,6 +1388,8 @@ definitions:
         type: boolean
       version:
         type: string
+      webhooks_enabled:
+        type: boolean
     type: object
   web.HTTPError:
     properties:
@@ -3004,6 +3042,154 @@ paths:
       summary: Add a user to a project
       tags:
       - sharing
+  /projects/{id}/webhooks:
+    get:
+      consumes:
+      - application/json
+      description: Get all api webhook targets for the specified project.
+      parameters:
+      - description: The page number. Used for pagination. If not provided, the first
+          page of results is returned.
+        in: query
+        name: page
+        type: integer
+      - description: The maximum number of items per bucket per page. This parameter
+          is limited by the configured maximum of items per page.
+        in: query
+        name: per_page
+        type: integer
+      - description: Project ID
+        in: path
+        name: id
+        required: true
+        type: integer
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: The list of all webhook targets
+          schema:
+            items:
+              $ref: '#/definitions/models.Webhook'
+            type: array
+        "500":
+          description: Internal server error
+          schema:
+            $ref: '#/definitions/models.Message'
+      security:
+      - JWTKeyAuth: []
+      summary: Get all api webhook targets for the specified project
+      tags:
+      - webhooks
+    put:
+      consumes:
+      - application/json
+      description: Create a webhook target which recieves POST requests about specified
+        events from a project.
+      parameters:
+      - description: Project ID
+        in: path
+        name: id
+        required: true
+        type: integer
+      - description: The webhook target object with required fields
+        in: body
+        name: webhook
+        required: true
+        schema:
+          $ref: '#/definitions/models.Webhook'
+      produces:
+      - application/json
+      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'
+      security:
+      - JWTKeyAuth: []
+      summary: Create a webhook target
+      tags:
+      - webhooks
+  /projects/{id}/webhooks/{webhookID}:
+    delete:
+      consumes:
+      - application/json
+      description: Delete any of the project's webhook targets.
+      parameters:
+      - description: Project ID
+        in: path
+        name: id
+        required: true
+        type: integer
+      - description: Webhook ID
+        in: path
+        name: webhookID
+        required: true
+        type: integer
+      produces:
+      - application/json
+      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'
+      security:
+      - JWTKeyAuth: []
+      summary: Deletes an existing webhook target
+      tags:
+      - webhooks
+    post:
+      consumes:
+      - application/json
+      description: Change a webhook target's events. You cannot change other values
+        of a webhook.
+      parameters:
+      - description: Project ID
+        in: path
+        name: id
+        required: true
+        type: integer
+      - description: Webhook ID
+        in: path
+        name: webhookID
+        required: true
+        type: integer
+      produces:
+      - application/json
+      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'
+      security:
+      - JWTKeyAuth: []
+      summary: Change a webhook target's events.
+      tags:
+      - webhooks
   /projects/{project}/shares:
     get:
       consumes:
@@ -5018,17 +5204,17 @@ paths:
       - application/json
       description: Returns all api tokens the current user has created.
       parameters:
-      - description: The page number for tasks. Used for pagination. If not provided,
+      - description: The page number, used for pagination. If not provided, the first
-          the first page of results is returned.
+          page of results is returned.
         in: query
         name: page
         type: integer
-      - description: The maximum number of tasks per bucket per page. This parameter
+      - description: The maximum number of tokens per page. This parameter is limited
-          is limited by the configured maximum of items per page.
+          by the configured maximum of items per page.
         in: query
         name: per_page
         type: integer
-      - description: Search tasks by task text.
+      - description: Search tokens by their title.
         in: query
         name: s
         type: string
@@ -5901,6 +6087,30 @@ paths:
       summary: Get users
       tags:
       - user
+  /webhooks/events:
+    get:
+      consumes:
+      - application/json
+      description: Get all possible webhook events to use when creating or updating
+        a webhook target.
+      produces:
+      - application/json
+      responses:
+        "200":
+          description: The list of all possible webhook events
+          schema:
+            items:
+              type: string
+            type: array
+        "500":
+          description: Internal server error
+          schema:
+            $ref: '#/definitions/models.Message'
+      security:
+      - JWTKeyAuth: []
+      summary: Get all possible webhook events
+      tags:
+      - webhooks
 securityDefinitions:
   BasicAuth:
     type: basic