Tiptap Docs

Webhooks in Collaboration

You can define a URL and we will call it every time a document has changed. This is useful for getting the JSON representation of the Yjs document in your own application.

We call your webhook URL when the document is saved to our database. This operation is debounced by 2-10 seconds. So your application won't be flooded by us. Right now we're only exporting the fragment default of the Yjs document.

Configure Webhooks

To configure webhooks for document and comments notifications:

  1. Navigate to the Collaboration settings in your account.
  2. Find the webhooks section and add your desired endpoint URL.

After adding your URL, the webhook is immediately live. You'll start receiving notifications for the specified events without any delay.

Add Comments support to your webhook

If you want to add webhook support for the comments feature and your collaboration app was created before March 2024, please upgrade your webhook as described below.

Example payload

All requests to your webhook URL will contain a header called X-Hocuspocus-Signature-256 that signs the entire message with your secret. You can find it in the settings of your Tiptap Collab app.

{
  "appName": '', // name of your app
  "name": '', // name of the document (URI encoded if necessary)
  "time": // current time as ISOString (new Date()).toISOString())
  "tiptapJson": {}, // JSON output from Tiptap (see https://tiptap.dev/guide/output#option-1-json): TiptapTransformer.fromYdoc()
  "ydocState"?: {}, // optionally contains the entire yDoc as base64. Contact us to enable this property!
  "clientsCount": 100,// number of currently connected clients
  "type": '', // the payload type (if the document was changed, this is DOCUMENT) ; only available if you are on webhooks v2
  "trigger": '' // what triggered the event (usually "document.saved") ; only available if you are on webhooks v2
}

Enable the Comments webhook

The webhook that supports comments is automatically enabled for all users that have created their account after March, 2024.

If your account was created before March, 2024 and you're using an older version of the webhook system, you'll need to manually enable the new comments webhooks. Here's how:

  1. In case you’ve already implemented a previous Collaboration webhook, make sure to check the type and trigger fields when processing incoming webhooks.
  2. Navigate to the Collaboration settings in your account.
  3. Locate the Webhook section and click on the "Update" button.

This upgrade is necessary to accommodate the introduction of multiple new events being routed to the same webhook endpoint, distinguished by a new type and trigger field.

If you do not wish to use the comments webhook, no upgrade is necessary.