Webhooks

Webhooks are http requests that are send from caisy to your system. This request can contain information about all the events that are happening in 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.

  
  

In an active project, to go to the section for webhooks in the ui click the cogwheel icon to access the preferences. Thereafter, go to "Development" and "Webhooks", and you'll see all you current webhooks.

To create an Webhook use the "create" button in top right corner. If you want to update an existing webhook, click on the table record.

Here is what your webhook might look like:

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

If you are developing a new integration or debugging you existing integration it can very helpful to check the activity log. Further you find the exact payload that have been sent to your url and can replay them locally.

Activity Log

Payload details

If you go on "View details" on your recent calls, you can see the exact payload. Note that your action you selected must at least be triggered once, otherwise you will not see any webhook calls. So you you selected "Document update" as action, you might need to publish any document first, in order to see any webhook calls. 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"
   }
}

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

you could debug this webhook event locally with the following curl command

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 a https secured url from ngrok like so:

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

Then you can use the new ngrok url in your webhook. Dot forget to include the path as well. Also probably best to duplicate the existing webhook for the usage with the tunnel url. So you got one for development and one that is intended for production.

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

Once you got your webhook up and running you might want to use our sdk to retrive further data from caisy or perform mutations.