Webhook Documentation Guide for Non-Technical Users

This guide will help you create webhook documentation using our reusable components. No coding experience required!

Overview

We've created a set of reusable components that make it easy to document webhooks consistently across all our APIs. You just need to:

1. Copy the template
2. Fill in your API-specific information
3. Save the file

Step-by-Step Guide

Step 1: Copy the Template

1. Go to docs/unified-apis/webhook-template.mdx
2. Copy the entire file content
3. Create a new file in your API's folder (e.g., docs/unified-apis/crm/webhooks.mdx)
4. Paste the template content

Step 2: Update the File Header

At the top of the file, you'll see a section between --- marks. Update these values:

---
title: Your API Webhooks        # Change to your API name
description: Real-time event notifications for your API activities
sidebar_position: 4             # Change based on your sidebar order
displayed_sidebar: yourSidebar  # Change to your API's sidebar
breadcrumb_label: Webhooks
---

Step 3: Update the Main Header

Find the <WebhookHeader> component and update:

<WebhookHeader 
  title="Your API Webhooks"  // Change to your API name
  description="Your description of what these webhooks do"
/>

Step 4: List Your Webhook Events

Find the <WebhookEventTable> component and update the events list:

<WebhookEventTable 
  events={[
    {
      eventType: "resource:created",  // Your event name
      description: "What happens",     // Brief description
      triggerConditions: "When this happens"  // What triggers it
    },
    // Add more events here
  ]}
/>

Step 5: Document Each Event in Detail

For each webhook event, you have two options:

Option A: Simple Events (Use WebhookPayloadExample)

For simple events with just a payload example:

<WebhookPayloadExample 
  eventType="resource:deleted"
  description="What this event does"
  payload={{
    // Your JSON payload here
    type: "resource:deleted",
    resource: {
      id: "123",
      name: "Example"
    }
  }}
  attributes={[
    { name: "resource.id", description: "What this field means" }
  ]}
/>

Option B: Complex Events (Use WebhookEvent)

For events that need detailed documentation:

<WebhookEvent 
  eventName="Resource Created"
  eventType="resource:created"
  description="Detailed description of when this fires"
  schema={[
    // List all fields in the webhook payload
    { name: "type", type: "string", required: true, description: "Always resource:created" },
    { name: "resource", type: "object", required: true, description: "The resource data", isParent: true },
    { name: "resource.id", type: "string", required: true, description: "Unique ID", nested: true }
  ]}
  examplePayload={{
    // Your example JSON payload
  }}
/>

Step 6: Update Code Examples

Update the code examples in the Best Practices section with relevant examples for your API:

<WebhookCodeExample 
  title="Your Example Title"
  description="What this example shows"
  code={`
// Your code example here
function handleWebhook() {
  // Code
}
`}
/>

Step 7: Update Troubleshooting

Update the troubleshooting section with common issues for your API:

<WebhookTroubleshooting 
  items={[
    {
      issue: "Common problem",
      solutions: [
        "First solution",
        "Second solution"
      ]
    }
  ]}
/>

Component Reference

WebhookEventTable

Shows a summary table of all webhook events.

What to provide:

• events: List of events with eventType, description, and triggerConditions

WebhookEvent

Shows detailed documentation for a complex webhook event.

What to provide:

• eventType: The technical event name (e.g., "resource:created")
• description: What triggers this event
• schema: List of all fields in the webhook payload
• examplePayload: A complete JSON example

WebhookPayloadExample

Shows a simple webhook event with just an example payload.

What to provide:

• eventType: The event name
• description: Brief description
• payload: Example JSON payload
• attributes: Optional list of field descriptions

WebhookCodeExample

Shows a code example.

What to provide:

• title: Example title
• description: What the example demonstrates
• code: The actual code

WebhookTroubleshooting

Shows common issues and solutions.

What to provide:

• items: List of issues with their solutions

Tips for Writing Good Webhook Documentation

1. Be Consistent: Use the same terminology throughout your documentation
2. Use Real Examples: Provide realistic JSON payloads that developers might actually receive
3. Explain Everything: Don't assume knowledge - explain what each field means
4. Group Related Events: Keep similar events together (e.g., all repository events, all user events)
5. Test Your Examples: Make sure your JSON examples are valid

Common Patterns

Nested Objects in Schema

When documenting nested objects in the schema:

schema={[
  { name: "user", type: "object", required: true, description: "User info", isParent: true },
  { name: "user.id", type: "string", required: true, description: "User ID", nested: true },
  { name: "user.name", type: "string", required: true, description: "User name", nested: true }
]}

Optional Fields

Mark optional fields with required: false:

{ name: "description", type: "string", required: false, description: "Optional description" }

Multiple Event Types

For APIs with many events, organize them by category:

## Event Details

### User Events
[User-related webhook events]

### Project Events
[Project-related webhook events]

### Task Events
[Task-related webhook events]

Need Help?

If you need help creating webhook documentation:

1. Look at the SCM webhooks example (docs/unified-apis/scm/webhooks-refactored.mdx)
2. Ask the engineering team for the webhook payload examples
3. Use the template as a starting point and customize as needed

Remember: The goal is to make it easy for developers to integrate with our webhooks. Clear, consistent documentation helps achieve that goal!