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.

Edit your webhook

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:


Fields

Field

Function

Example

Name

Freely pickable internal name

foo

Method

Http Method to use in the request

POST

URL

Remote URL where the requests are send to

https://my-nice-app.io/api/integration/webhooks/caisy

Actions

Type of actions you want to listen to

Document Update, Document Delete

Header

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.

Actions

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.

Action

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


Debugging

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


Working with local dev server

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"
   }
}'

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 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.