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.

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
  "users": [] // list of users who changed the content since the last webhook ("sub" field from the JWT)
}

Retries

Webhooks are not retried by default, but you can enable retries by setting webhook_retries to 1 (see Configure Runtime). The retry schedule is as follows:

• 1st retry: 5 seconds after the initial attempt
• 2nd retry: 15 seconds after the last attempt
• 3rd retry: 2 minutes after the last attempt
• 4th retry: 10 minute after the last attempt
• 5th retry: 30 minutes after the last attempt
• 6th retry: 3 hours after the last attempt

All retries include a header X-Hocuspocus-Retry with the current retry count. The time property in the payload is the timestamp of the initial attempt.

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.