Updated webhook endpoint

Author: KillerX

backend/internal/database/migrations/00030_rename_external_content_event_columns.sql

@@ -0,0 +1,23 @@
+-- +goose Up
+-- +goose StatementBegin
+
+-- Rename columns in external_content_events table
+ALTER TABLE external_content_events RENAME COLUMN content_id TO task_id;
+ALTER TABLE external_content_events RENAME COLUMN reading_plan_id TO plan_id;
+
+-- Add consumed_at timestamp column
+ALTER TABLE external_content_events ADD COLUMN consumed_at TIMESTAMPTZ;
+
+-- +goose StatementEnd
+
+-- +goose Down
+-- +goose StatementBegin
+
+-- Remove consumed_at column
+ALTER TABLE external_content_events DROP COLUMN consumed_at;
+
+-- Revert column renames
+ALTER TABLE external_content_events RENAME COLUMN task_id TO content_id;
+ALTER TABLE external_content_events RENAME COLUMN plan_id TO reading_plan_id;
+
+-- +goose StatementEnd

backend/internal/database/queries/external_content_events.sql

@@ -1,23 +1,23 @@
 -- name: CreateExternalContentEvent :one
-INSERT INTO external_content_events (id, person_id, content_id, reading_plan_id, source, received_at, content_progress)
-VALUES (@id, @personid::uuid, @contentid::text, @readingplanid::text, @source::text, @receivedat::timestamptz, @contentprogress)
-RETURNING id, person_id, content_id, reading_plan_id, source, received_at, content_progress;
+INSERT INTO external_content_events (id, person_id, task_id, plan_id, source, received_at, content_progress, consumed_at)
+VALUES (@id, @personid::uuid, @taskid::text, @planid::text, @source::text, @receivedat::timestamptz, @contentprogress, @consumedat::timestamptz)
+RETURNING id, person_id, task_id, plan_id, source, received_at, content_progress, consumed_at;
 
 -- name: GetExternalContentEventByID :one
-SELECT id, person_id, content_id, reading_plan_id, source, received_at, content_progress
+SELECT id, person_id, task_id, plan_id, source, received_at, content_progress, consumed_at
 FROM external_content_events
 WHERE id = @id;
 
 -- name: GetExternalContentEventsByPersonID :many
-SELECT id, person_id, content_id, reading_plan_id, source, received_at, content_progress
+SELECT id, person_id, task_id, plan_id, source, received_at, content_progress, consumed_at
 FROM external_content_events
 WHERE person_id = @personid::uuid
 ORDER BY received_at DESC
 LIMIT CASE WHEN @querylimit::int IS NULL THEN NULL ELSE @querylimit::int END
 OFFSET CASE WHEN @queryoffset::int IS NULL THEN 0 ELSE @queryoffset::int END;
 
 -- name: GetExternalContentEventsBySource :many
-SELECT id, person_id, content_id, reading_plan_id, source, received_at, content_progress
+SELECT id, person_id, task_id, plan_id, source, received_at, content_progress, consumed_at
 FROM external_content_events
 WHERE source = @source::text
 ORDER BY received_at DESC

backend/internal/database/sqlc/external_content_events.sql.go

@@ -19,10 +19,11 @@ type WebhookHandler struct {
 
 // ContentEventRequest represents the incoming webhook payload for content events
 type ContentEventRequest struct {
-	PersonID        string   `json:"person_id" binding:"required"`
-	ContentID       string   `json:"content_id" binding:"required"`
-	ReadingPlanID   *string  `json:"reading_plan_id"`
-	ContentProgress *float64 `json:"content_progress"`
+	PersonID        string    `json:"person_id" binding:"required"`
+	TaskID          string    `json:"task_id" binding:"required"`
+	PlanID          *string   `json:"plan_id"`
+	Timestamp       time.Time `json:"timestamp" binding:"required"`
+	ContentProgress *float64  `json:"content_progress"`
 }
 
 // HandleContentEvent handles POST requests for external content completion events
@@ -81,7 +82,7 @@ func (h *WebhookHandler) HandleContentEvent(c *gin.Context) {
 	slog.Info("webhook: creating content event",
 		"event_id", eventID,
 		"person_id", req.PersonID,
-		"content_id", req.ContentID,
+		"task_id", req.TaskID,
 		"source", sourceStr,
 	)
 
@@ -93,21 +94,30 @@ func (h *WebhookHandler) HandleContentEvent(c *gin.Context) {
 		return
 	}
 
-	// Prepare reading_plan_id (nullable)
-	readingPlanID := ""
-	if req.ReadingPlanID != nil {
-		readingPlanID = *req.ReadingPlanID
+	// Prepare plan_id (nullable)
+	planID := ""
+	if req.PlanID != nil {
+		planID = *req.PlanID
+	}
+
+	// Convert consumed_at timestamp to pgtype.Timestamptz
+	var consumedAtPg pgtype.Timestamptz
+	if err := consumedAtPg.Scan(req.Timestamp); err != nil {
+		slog.Error("webhook: failed to convert consumed_at timestamp", "error", err)
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "internal server error"})
+		return
 	}
 
 	// Insert event into database
 	event, err := h.DB.Queries.CreateExternalContentEvent(ctx, sqlc.CreateExternalContentEventParams{
 		ID:              eventID,
 		Personid:        personPgUUID,
-		Contentid:       req.ContentID,
-		Readingplanid:   readingPlanID,
+		Taskid:          req.TaskID,
+		Planid:          planID,
 		Source:          sourceStr,
 		Receivedat:      receivedAtPg,
 		Contentprogress: contentProgress,
+		Consumedat:      consumedAtPg,
 	})
 	if err != nil {
 		slog.Error("webhook: failed to create content event",

backend/internal/database/sqlc/models.go

@@ -40,8 +40,9 @@ Submit a new content completion event.
 ```json
 {
   "person_id": "550e8400-e29b-41d4-a716-446655440000",
-  "content_id": "article-123",
-  "reading_plan_id": "plan-456",
+  "task_id": "article-123",
+  "plan_id": "plan-456",
+  "timestamp": "2025-01-15T14:30:00Z",
   "content_progress": 0.75
 }
 ```
@@ -51,8 +52,9 @@ Submit a new content completion event.
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | person_id | string (UUID) | Yes | The Brunstad TV person_id (UUID format) |
-| content_id | string | Yes | External content identifier |
-| reading_plan_id | string | No | External reading plan identifier (optional) |
+| task_id | string | Yes | External task identifier |
+| plan_id | string | No | External plan identifier (optional) |
+| timestamp | string (ISO8601) | Yes | When the content was consumed (RFC3339/ISO8601 format) |
 | content_progress | float | No | Content completion progress (0.01 to 1.1, where 1.0 = 100%). Values outside this range are ignored and stored as NULL. |
 
 #### Success Response

backend/internal/handlers/webhook.go

@@ -0,0 +1,13 @@
+type: folder
+model: folder
+id: fl_ContentEvents
+createdAt: 2025-12-03T10:15:00
+updatedAt: 2025-12-03T10:15:00
+workspaceId: wk_XKsmbMdFg7
+folderId: null
+authentication: {}
+authenticationType: null
+description: ''
+headers: []
+name: Webhooks
+sortPriority: 3000.0

docs/external-content-events-api.md

@@ -0,0 +1,32 @@
+type: http_request
+model: http_request
+id: rq_ContentEvent
+createdAt: 2025-12-03T10:15:00
+updatedAt: 2025-12-03T09:18:19.268239
+workspaceId: wk_XKsmbMdFg7
+folderId: fl_ContentEvents
+authentication:
+  key: Bearer
+  token: example-api-key-12345
+authenticationType: bearer
+body:
+  text: |
+    {
+      "person_id": "550e8400-e29b-41d4-a716-446655440000",
+      "task_id": "article-123",
+      "plan_id": "plan-456",
+      "timestamp": "2025-01-15T14:30:00Z",
+      "content_progress": 0.75
+    }
+bodyType: application/json
+description: Submit a content completion event from an external system
+headers:
+- enabled: true
+  name: Content-Type
+  value: application/json
+  id: hdr_ContentType
+method: POST
+name: Submit Content Event
+sortPriority: 0.0
+url: ${[ HOST ]}/api/v1/content-events
+urlParameters: []