mvaldes14
/
vikunja-api
forked from vikunja/vikunja
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

feat: webhooks (#1624) 

Reviewed-on: vikunja/api#1624
This commit is contained in:
konrad 2023-10-20 11:06:36 +00:00
parent a1d0541a7a 55d345e236
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 = `{
},
"version": {
"type": "string"
},
"webhooks_enabled": {
"type": "boolean"
}
}
},

316
pkg/swagger/swagger.json
View File

@ -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"
}
}
},

220
pkg/swagger/swagger.yaml
View File

@ -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,
the first page of results is returned.
- 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 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.
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