Webhooks are HTTP requests sent from caisy to your system. These requests can contain information about all the events that are taking place within the project.

They are very helpful if you are building external features. Like

  • form submission

  • cache invalidation

  • trigger ci/cd pipeline

  • data synchronization

  • search index updates

  • email sending

  • etc.

caisy screenshot interface development webhooks

To access the webhooks section in an active project, click on the cogwheel icon to open the preferences. Then, navigate to the "Development" section and select "Webhooks" to view all of your current webhooks.

Edit your webhook

To create a webhook, use the 'Create' button in the top right corner. To update an existing webhook, click on the corresponding record in the table.

Here is what your webhook might look like:

caisy screenshot interface user details activity log






Freely pickable internal name



Http Method to use in the request



Remote URL where the requests are send to



Type of actions you want to listen to

Document Update, Document Delete


Defines headers as key and value that are send the in the request

x-auth ak81jatt3gat3gatdvbatga

Security note: Since the webhook endpoint needs to be public available, use an authentication header. This header lets you verify that the request is acutely coming from caisy. Otherwise anybody could do the same requests against your webhook endpoint.


caisy screenshot interface action log

For every action you add to your webhook, you are listening to more events. The action defines which types of events you are listening to.


Event send when

Document field update

a field inside a document/component/asset was updated

Document create

document has been created

Document update

document status has been changed: draft, published, etc...

(this does not include document field updates)

Document delete

document was deleted

Blueprint create

blueprint has been created

Blueprint update

blueprint has been updated

Blueprint delete

blueprint was deleted

Project member assigned

a new member was assigned to the project or a role of a member was changed

Project member deassigned

a member was removed from the project


If you are developing a new integration or debugging an existing one, it can be very helpful to check the activity log. There, you will find the exact payload that has been sent to your URL and you can replay it locally.

Activity Log

caisy screenshot interface activity log

Payload details

By going to "View details" on your recent calls, you can view the exact payload. Note that your selected action must be triggered at least once, otherwise you won't see any webhook calls. In order to see webhook calls for the "Document update" action, you need to first publish a document. The detail page of a single webhook calls might look like this:

caisy screenshot interface request code

with this as the body


Working with local dev server

Assuming you run your server locally on port 3000 and use the path /api/v1/webhook/caisy.

You can use the following curl command to debug this webhook event locally:

curl localhost:3000/api/v1/webhook/caisy/api/v1/webhook/caisy -H "x-auth: a92ja7h1ahaf1ao9aa" -H Content-Type: application/json -d '{

Proxy using tunneling tool

Another method to debug webhooks locally would be to use a tunneling tool. This tools will proxy the webhooks in real time to your local running dev server. Here is an example using ngrok. To start your proxy server run:

ngrok http 3000

You will get an HTTPS secured URL from ngrok, similar to this:

https://8cd2-91-49-126-216.eu.ngrok.io -> http://localhost:3000

Then you can use the new ngrok URL in your webhook. Don't forget to include the path as well. It's probably best to duplicate the existing webhook for usage with the tunnel URL, so you have one for development and one that is intended for production.

As an alternative to ngrok, you can also use localtunnel, which works in the same way: https://github.com/localtunnel/localtunnel

Once you have your webhook up and running, you might want to use our SDK to retrieve further data from caisy or perform mutations.