Yorkie

If you want to update this page or add new content, please submit a pull request to the Homepage.

Event Webhook

The Event Webhook allows you to receive notifications when specific events occur in your Yorkie documents. Unlike the Auth Webhook which handles authorization, the Event Webhook is designed for integrations and notifications when document state changes.

How It Works

When a configured event occurs, Yorkie sends an HTTP POST request to your webhook endpoint with details about the event.

  1. A client makes changes to a document
  2. Yorkie server processes the changes
  3. If the event matches configured triggers, Yorkie sends a webhook request
  4. Your server processes the event (e.g., send notifications, update external systems)
  5. Your server responds to acknowledge receipt

Supported Events

EventDescription
DocumentRootChangedTriggered when the document's root content is modified

Setup and Configuration

1. Configure the Event Webhook

You can configure the Event Webhook using the Yorkie CLI:

# Set the webhook URL and enable the DocumentRootChanged event
yorkie project update [project-name] \
  --event-webhook-url "https://your-server.com/webhook" \
  --event-webhook-events-add "DocumentRootChanged"

To disable specific events:

yorkie project update [project-name] \
  --event-webhook-events-rm "DocumentRootChanged"

To enable all events:

yorkie project update [project-name] \
  --event-webhook-events-add "ALL"

2. Webhook Request Format

When an event is triggered, Yorkie sends a POST request with the following JSON payload:

{
  "type": "DocumentRootChanged",
  "attributes": {
    "key": "your-document-key",
    "issuedAt": "2025-01-02T15:04:05.000Z"
  }
}
FieldDescription
typeThe event type that triggered the webhook
attributes.keyThe key of the document that triggered the event
attributes.issuedAtISO 8601 timestamp when the event occurred

3. Webhook Response

Your webhook server should respond with an HTTP status code:

Status CodeMeaning
200 OKEvent received and processed successfully
OtherYorkie will retry the request based on retry configuration

Retry Configuration

The Event Webhook includes configurable retry behavior with exponential backoff for failed requests.

SettingDefaultDescription
event-webhook-max-retries10Maximum number of retry attempts
event-webhook-min-wait-interval100msMinimum wait time between retries
event-webhook-max-wait-interval3sMaximum wait time between retries
event-webhook-request-timeout3sTimeout for each webhook request

Configure Retry Settings

yorkie project update [project-name] \
  --event-webhook-max-retries 5 \
  --event-webhook-min-wait-interval 200ms \
  --event-webhook-max-wait-interval 5s \
  --event-webhook-request-timeout 10s

Example Webhook Server

Here's a simple example of an Express.js webhook server:

1const express = require('express');
2const app = express();
3

4app.use(express.json());
5

6app.post('/webhook', (req, res) => {
7  const { type, attributes } = req.body;
8

9  console.log(`Event: ${type}`);
10  console.log(`Document: ${attributes.key}`);
11  console.log(`Time: ${attributes.issuedAt}`);
12

13  // Process the event (e.g., send notifications, update cache)
14

15  res.status(200).send('OK');
16});
17

18app.listen(3000, () => {
19  console.log('Webhook server listening on port 3000');
20});

Use Cases

  • Real-time notifications: Notify users when a shared document is updated
  • External system sync: Keep external databases or services in sync with document changes
  • Audit logging: Record document change events for compliance
  • Cache invalidation: Invalidate caches when documents change