[Issue]: Write plugin webhook implementation guide

[dawidurbanski]

[Issue]: Write Plugin Webhook Implementation Guide

Parent Epic: #57 - UDL as Production Data Layer
Phase: 6 - Documentation
Estimated Time: 0.5 day

Summary

Write documentation explaining how plugin authors can implement webhook handlers in their plugins, including signature verification, payload processing, and node updates.

Context from Epic

The epic shows the webhook registration API:

registerWebhook({
  path: 'contentful-update',
  handler: async (req, res) => { /* process, update nodes */ },
  verifySignature: (req) => verifyContentfulSignature(req, secret),
});

Plugin authors need a guide to implement this in their plugins.

Technical Specification

Documentation Content

Plugin Webhook Implementation Guide:

1. Introduction

   • What webhooks enable (real-time updates)
   • How UDL routes webhooks to plugins

2. Registering Webhooks

   export async function sourceNodes({ actions, registerWebhook, options }) {
     // Source initial data...
     
     registerWebhook({
       path: 'entry-update',
       description: 'Handle Contentful entry updates',
       handler: async (req, res, context) => {
         // Process webhook
       },
       verifySignature: (req, body) => {
         // Verify signature
       },
     });
   }

3. Handler Implementation

   • Accessing raw body and parsed JSON
   • Using context.actions to update nodes
   • Returning appropriate responses

4. Signature Verification

   • Why verification matters
   • Platform-specific examples (Contentful, Shopify)
   • Handling verification failures

5. Complete Example

   • Full Contentful webhook implementation
   • Full Shopify webhook implementation

Files to Create

• docs/content/5.advanced/3.plugin-webhooks.md

Implementation Tasks

• Write introduction explaining webhook flow
• Document registerWebhook API with examples
• Add handler implementation guide
• Add signature verification examples for Contentful/Shopify
• Include complete working examples
• Add troubleshooting section

Acceptance Criteria

• Guide covers complete webhook implementation flow
• Code examples are correct and tested
• Signature verification is explained
• Examples for Contentful and Shopify included
• Documentation follows existing style

Dependencies

• Blocked by: [Issue]: Add plugin webhook registration API #60 (webhook registration API), [Issue]: Add webhook HTTP routing #61 (webhook routing)
• Blocks: None
• Related: [Epic]: UDL as Production Data Layer #57 (parent epic)

Definition of Done

• Documentation complete and reviewed
• Examples tested and working
• PR reviewed and merged