Webhooks

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.

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.

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:

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.

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

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:

with this as the body

{
   "event_id":"23fd61a1-3423-4d8c-a53a-effb2d89e3ab",
   "metadata":{
      "blueprint_id":"",
      "document_id":"de0a74d8-e472-4dd1-909c-d233f14f4da5",
      "document_status_id":2
   },
   "scope":{
      "project_id":"713bef0a-25f7-4d68-a4ec-23b8f5926459"
   },
   "webhook":{
      "trigger":"document_update",
      "webhook_id":"b5ee7588-6874-461d-9e30-f6e0e1391d63"
   }
}

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 '{
   "event_id":"23fd61a1-3423-4d8c-a53a-effb2d89e3ab",
   "metadata":{
      "blueprint_id":"",
      "document_id":"de0a74d8-e472-4dd1-909c-d233f14f4da5",
      "document_status_id":2
   },
   "scope":{
      "project_id":"713bef0a-25f7-4d68-a4ec-23b8f5926459"
   },
   "webhook":{
      "trigger":"document_update",
      "webhook_id":"b5ee7588-6874-461d-9e30-f6e0e1391d63"
   }
}'

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.