Add Event Webhook Support with DocRootChanged Event

api/converter/from_pb.go

@@ -55,6 +55,8 @@ func FromProject(pbProject *api.Project) *types.Project {
 		Name:                      pbProject.Name,
 		AuthWebhookURL:            pbProject.AuthWebhookUrl,
 		AuthWebhookMethods:        pbProject.AuthWebhookMethods,
+		EventWebhookURL:           pbProject.EventWebhookUrl,
+		EventWebhookTypes:         pbProject.EventWebhookTypes,
 		ClientDeactivateThreshold: pbProject.ClientDeactivateThreshold,
 		PublicKey:                 pbProject.PublicKey,
 		SecretKey:                 pbProject.SecretKey,
@@ -922,6 +924,12 @@ func FromUpdatableProjectFields(pbProjectFields *api.UpdatableProjectFields) (*t
 	if pbProjectFields.AuthWebhookMethods != nil {
 		updatableProjectFields.AuthWebhookMethods = &pbProjectFields.AuthWebhookMethods.Methods
 	}
+	if pbProjectFields.EventWebhookUrl != nil {
+		updatableProjectFields.EventWebhookURL = &pbProjectFields.EventWebhookUrl.Value
+	}
+	if pbProjectFields.EventWebhookTypes != nil {
+		updatableProjectFields.EventWebhookTypes = &pbProjectFields.EventWebhookTypes.Types
+	}
 	if pbProjectFields.ClientDeactivateThreshold != nil {
 		updatableProjectFields.ClientDeactivateThreshold = &pbProjectFields.ClientDeactivateThreshold.Value
 	}

api/converter/to_pb.go

@@ -59,6 +59,8 @@ func ToProject(project *types.Project) *api.Project {
 		Name:                      project.Name,
 		AuthWebhookUrl:            project.AuthWebhookURL,
 		AuthWebhookMethods:        project.AuthWebhookMethods,
+		EventWebhookUrl:           project.EventWebhookURL,
+		EventWebhookTypes:         project.EventWebhookTypes,
 		ClientDeactivateThreshold: project.ClientDeactivateThreshold,
 		PublicKey:                 project.PublicKey,
 		SecretKey:                 project.SecretKey,
@@ -562,6 +564,16 @@ func ToUpdatableProjectFields(fields *types.UpdatableProjectFields) (*api.Updata
 	} else {
 		pbUpdatableProjectFields.AuthWebhookMethods = nil
 	}
+	if fields.EventWebhookURL != nil {
+		pbUpdatableProjectFields.EventWebhookUrl = &wrapperspb.StringValue{Value: *fields.EventWebhookURL}
+	}
+	if fields.EventWebhookTypes != nil {
+		pbUpdatableProjectFields.EventWebhookTypes = &api.UpdatableProjectFields_EventWebhookTypes{
+			Types: *fields.EventWebhookTypes,
+		}
+	} else {
+		pbUpdatableProjectFields.EventWebhookTypes = nil
+	}
 	if fields.ClientDeactivateThreshold != nil {
 		pbUpdatableProjectFields.ClientDeactivateThreshold = &wrapperspb.StringValue{
 			Value: *fields.ClientDeactivateThreshold,

api/docs/yorkie/v1/admin.openapi.yaml

@@ -1463,11 +1463,10 @@ components:
       type: object
     yorkie.v1.Operation.Select:
       additionalProperties: false
-      description: |-
-        NOTE(hackerwins): Select Operation is not used in the current version.
-         In the previous version, it was used to represent selection of Text.
-         However, it has been replaced by Presence now. It is retained for backward
-         compatibility purposes.
+      description: "NOTE(hackerwins): Select Operation is not used in the current
+        version.\r\n In the previous version, it was used to represent selection of
+        Text.\r\n However, it has been replaced by Presence now. It is retained for
+        backward\r\n compatibility purposes."
       properties:
         executedAt:
           $ref: '#/components/schemas/yorkie.v1.TimeTicket'
@@ -1826,6 +1825,18 @@ components:
           description: ""
           title: created_at
           type: object
+        eventWebhookTypes:
+          additionalProperties: false
+          description: ""
+          items:
+            type: string
+          title: event_webhook_types
+          type: array
+        eventWebhookUrl:
+          additionalProperties: false
+          description: ""
+          title: event_webhook_url
+          type: string
         id:
           additionalProperties: false
           description: ""
@@ -2132,6 +2143,18 @@ components:
           description: ""
           title: client_deactivate_threshold
           type: object
+        eventWebhookTypes:
+          $ref: '#/components/schemas/yorkie.v1.UpdatableProjectFields.EventWebhookTypes'
+          additionalProperties: false
+          description: ""
+          title: event_webhook_types
+          type: object
+        eventWebhookUrl:
+          $ref: '#/components/schemas/google.protobuf.StringValue'
+          additionalProperties: false
+          description: ""
+          title: event_webhook_url
+          type: object
         name:
           $ref: '#/components/schemas/google.protobuf.StringValue'
           additionalProperties: false
@@ -2153,6 +2176,19 @@ components:
           type: array
       title: AuthWebhookMethods
       type: object
+    yorkie.v1.UpdatableProjectFields.EventWebhookTypes:
+      additionalProperties: false
+      description: ""
+      properties:
+        types:
+          additionalProperties: false
+          description: ""
+          items:
+            type: string
+          title: types
+          type: array
+      title: EventWebhookTypes
+      type: object
     yorkie.v1.UpdateProjectRequest:
       additionalProperties: false
       description: ""

api/docs/yorkie/v1/cluster.openapi.yaml

@@ -269,6 +269,18 @@ components:
           description: ""
           title: created_at
           type: object
+        eventWebhookTypes:
+          additionalProperties: false
+          description: ""
+          items:
+            type: string
+          title: event_webhook_types
+          type: array
+        eventWebhookUrl:
+          additionalProperties: false
+          description: ""
+          title: event_webhook_url
+          type: string
         id:
           additionalProperties: false
           description: ""

api/docs/yorkie/v1/resources.openapi.yaml

@@ -228,9 +228,8 @@ components:
       type: object
     yorkie.v1.ChangePack:
       additionalProperties: false
-      description: |-
-        ChangePack is a message that contains all changes that occurred in a document.
-         It is used to synchronize changes between clients and servers.
+      description: "ChangePack is a message that contains all changes that occurred
+        in a document.\r\n It is used to synchronize changes between clients and servers."
       properties:
         changes:
           additionalProperties: false
@@ -972,11 +971,10 @@ components:
       type: object
     yorkie.v1.Operation.Select:
       additionalProperties: false
-      description: |-
-        NOTE(hackerwins): Select Operation is not used in the current version.
-         In the previous version, it was used to represent selection of Text.
-         However, it has been replaced by Presence now. It is retained for backward
-         compatibility purposes.
+      description: "NOTE(hackerwins): Select Operation is not used in the current
+        version.\r\n In the previous version, it was used to represent selection of
+        Text.\r\n However, it has been replaced by Presence now. It is retained for
+        backward\r\n compatibility purposes."
       properties:
         executedAt:
           $ref: '#/components/schemas/yorkie.v1.TimeTicket'
@@ -1335,6 +1333,18 @@ components:
           description: ""
           title: created_at
           type: object
+        eventWebhookTypes:
+          additionalProperties: false
+          description: ""
+          items:
+            type: string
+          title: event_webhook_types
+          type: array
+        eventWebhookUrl:
+          additionalProperties: false
+          description: ""
+          title: event_webhook_url
+          type: string
         id:
           additionalProperties: false
           description: ""
@@ -1400,10 +1410,8 @@ components:
       type: object
     yorkie.v1.Snapshot:
       additionalProperties: false
-      description: |-
-        ///////////////////////////////////////
-         Messages for Snapshot               //
-        ///////////////////////////////////////
+      description: "///////////////////////////////////////\r\n Messages for Snapshot
+        \              //\r\n///////////////////////////////////////"
       properties:
         presences:
           additionalProperties: false
@@ -1687,6 +1695,18 @@ components:
           description: ""
           title: client_deactivate_threshold
           type: object
+        eventWebhookTypes:
+          $ref: '#/components/schemas/yorkie.v1.UpdatableProjectFields.EventWebhookTypes'
+          additionalProperties: false
+          description: ""
+          title: event_webhook_types
+          type: object
+        eventWebhookUrl:
+          $ref: '#/components/schemas/google.protobuf.StringValue'
+          additionalProperties: false
+          description: ""
+          title: event_webhook_url
+          type: object
         name:
           $ref: '#/components/schemas/google.protobuf.StringValue'
           additionalProperties: false
@@ -1708,6 +1728,19 @@ components:
           type: array
       title: AuthWebhookMethods
       type: object
+    yorkie.v1.UpdatableProjectFields.EventWebhookTypes:
+      additionalProperties: false
+      description: ""
+      properties:
+        types:
+          additionalProperties: false
+          description: ""
+          items:
+            type: string
+          title: types
+          type: array
+      title: EventWebhookTypes
+      type: object
     yorkie.v1.User:
       additionalProperties: false
       description: ""

api/docs/yorkie/v1/yorkie.openapi.yaml

@@ -457,9 +457,8 @@ components:
       type: object
     yorkie.v1.ChangePack:
       additionalProperties: false
-      description: |-
-        ChangePack is a message that contains all changes that occurred in a document.
-         It is used to synchronize changes between clients and servers.
+      description: "ChangePack is a message that contains all changes that occurred
+        in a document.\r\n It is used to synchronize changes between clients and servers."
       properties:
         changes:
           additionalProperties: false
@@ -977,11 +976,10 @@ components:
       type: object
     yorkie.v1.Operation.Select:
       additionalProperties: false
-      description: |-
-        NOTE(hackerwins): Select Operation is not used in the current version.
-         In the previous version, it was used to represent selection of Text.
-         However, it has been replaced by Presence now. It is retained for backward
-         compatibility purposes.
+      description: "NOTE(hackerwins): Select Operation is not used in the current
+        version.\r\n In the previous version, it was used to represent selection of
+        Text.\r\n However, it has been replaced by Presence now. It is retained for
+        backward\r\n compatibility purposes."
       properties:
         executedAt:
           $ref: '#/components/schemas/yorkie.v1.TimeTicket'

api/types/event_webhook.go

@@ -0,0 +1,42 @@
+/*
+ * Copyright 2025 The Yorkie Authors. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package types
+
+// EventWebhookType represents event webhook type
+type EventWebhookType string
+
+const (
+	// DocRootChanged is an event that indicates the document's content was modified.
+	DocRootChanged EventWebhookType = "DocumentRootChanged"
+)
+
+// IsValidEventType checks whether the given event type is valid.
+func IsValidEventType(eventType string) bool {
+	return eventType == string(DocRootChanged)
+}
+
+// EventWebhookAttribute represents the attribute of the webhook.
+type EventWebhookAttribute struct {
+	Key      string `json:"key"`
+	IssuedAt string `json:"issuedAt"`
+}
+
+// EventWebhookRequest represents the request of the webhook.
+type EventWebhookRequest struct {
+	Type       EventWebhookType      `json:"type"`
+	Attributes EventWebhookAttribute `json:"attributes"`
+}

api/types/events/events.go

@@ -30,6 +30,10 @@ const (
 	// modified by a change.
 	DocChangedEvent DocEventType = "document-changed"
 
+	// DocRootChangedEvent is an event indicating that document's root content
+	// is being changed by operation.
+	DocRootChangedEvent DocEventType = "document-root-changed"
+
 	// DocWatchedEvent is an event that occurs when document is watched
 	// by other clients.
 	DocWatchedEvent DocEventType = "document-watched"
@@ -43,6 +47,16 @@ const (
 	DocBroadcastEvent DocEventType = "document-broadcast"
 )
 
+// WebhookType returns a matched event webhook type.
+func (t DocEventType) WebhookType() types.EventWebhookType {
+	switch t {
+	case DocRootChangedEvent:
+		return types.DocRootChanged
+	default:
+		return ""
+	}
+}
+
 // DocEventBody includes additional data specific to the DocEvent.
 type DocEventBody struct {
 	Topic   string

api/types/project.go

@@ -38,6 +38,12 @@ type Project struct {
 	// AuthWebhookMethods is the methods that run the authorization webhook.
 	AuthWebhookMethods []string `json:"auth_webhook_methods"`
 
+	// EventWebhookURL is the url of the event webhook.
+	EventWebhookURL string `json:"event_webhook_url"`
+
+	// EventWebhookTypes is the types that send the event webhook.
+	EventWebhookTypes []string `json:"event_webhook_types"`
+
 	// ClientDeactivateThreshold is the time after which clients in
 	// specific project are considered deactivate for housekeeping.
 	ClientDeactivateThreshold string `bson:"client_deactivate_threshold"`
@@ -73,3 +79,22 @@ func (p *Project) RequireAuth(method Method) bool {
 
 	return false
 }
+
+// RequireEventWebhook returns whether the given method requires to send event webhook.
+func (p *Project) RequireEventWebhook(eventType EventWebhookType) bool {
+	if len(p.EventWebhookURL) == 0 {
+		return false
+	}
+
+	if len(p.EventWebhookTypes) == 0 {
+		return false
+	}
+
+	for _, t := range p.EventWebhookTypes {
+		if EventWebhookType(t) == eventType {
+			return true
+		}
+	}
+
+	return false
+}