Webhooks #

Starting with version 0.22.0, Vikunja allows you to define webhooks to notify other services of events happening within Vikunja.

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 for information about how to create webhooks programatically.

Available events and their payload #

All events registered as webhook events in the event listeners definition can be used as webhook target.

A webhook payload will look similar to this:

{
	"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 for more information about how to validate the HMAC signature.

Hosting webhook infrastructure #

Vikunja has support to use 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 if you’re not the only one using your Vikunja instance.

Check out webhooks.fyi for more information about the attack vector and reasoning to prevent this.