@editframe/create 0.44.0 → 0.45.0

package/dist/skills/editframe-webhooks/references/testing.md

@@ -0,0 +1,409 @@
+---
+title: Testing Webhooks
+description: Test Editframe webhook endpoints locally using ngrok tunnels, webhook.site inspection, and the CLI test command.
+type: how-to
+nav:
+  parent: "Testing"
+  priority: 4
+---
+
+# Testing Webhooks
+
+Test your webhook endpoint before deploying to production using local tunneling, test services, and the Editframe dashboard.
+
+## Local Testing with ngrok
+
+Test webhooks locally by exposing your development server with ngrok:
+
+### 1. Install ngrok
+
+```bash
+# macOS (Homebrew)
+brew install ngrok
+
+# Or download from https://ngrok.com/download
+```
+
+### 2. Start Your Local Server
+
+```bash
+# Start your application
+npm run dev
+
+# Server running on http://localhost:3000
+```
+
+### 3. Create ngrok Tunnel
+
+```bash
+# Expose port 3000
+ngrok http 3000
+```
+
+ngrok will output:
+```
+Forwarding  https://abc123.ngrok.io -> http://localhost:3000
+```
+
+### 4. Configure Webhook URL
+
+Update your API key's webhook URL to the ngrok URL:
+
+```
+https://abc123.ngrok.io/webhooks/editframe
+```
+
+You can do this via:
+- Editframe dashboard → API Keys → Edit
+- Or programmatically via API
+
+### 5. Trigger Test Webhooks
+
+Trigger events to test your endpoint:
+
+```typescript
+import { Client, createRender } from "@editframe/api";
+
+const client = new Client(process.env.EDITFRAME_API_KEY);
+
+// Create a render - triggers render.created webhook
+const render = await createRender(client, {
+  html: `<ef-timegroup mode="contain" class="w-[1920px] h-[1080px]">
+    <ef-text>Test</ef-text>
+  </ef-timegroup>`,
+  width: 1920,
+  height: 1080,
+  fps: 30,
+});
+
+// Wait for completion - triggers render.completed webhook
+console.log("Check your local server for webhook events");
+```
+
+### 6. Monitor Requests
+
+View all webhook requests in the ngrok dashboard:
+```
+http://127.0.0.1:4040
+```
+
+The dashboard shows:
+- Request headers (including `X-Webhook-Signature`)
+- Request body (webhook event)
+- Response status and body
+- Timing information
+
+## Testing with webhook.site
+
+Use webhook.site to inspect webhook payloads without writing code:
+
+### 1. Get a Test URL
+
+Visit [webhook.site](https://webhook.site) to get a unique URL:
+```
+https://webhook.site/abc-123-def
+```
+
+### 2. Configure Webhook
+
+Set your API key's webhook URL to the webhook.site URL.
+
+### 3. Trigger Events
+
+Create renders or upload files to trigger webhooks.
+
+### 4. Inspect Payloads
+
+View webhook requests in webhook.site's interface:
+- Full request headers
+- JSON payload
+- Signature verification (manual)
+
+**Note**: webhook.site doesn't verify signatures. Use this for payload inspection only.
+
+## Test Webhook from Dashboard
+
+Send test webhooks directly from the Editframe dashboard:
+
+### 1. Navigate to API Key
+
+Go to your API key detail page:
+```
+https://editframe.com/resource/api_keys/<key-id>
+```
+
+### 2. Send Test Webhook
+
+1. Click "Test Webhook"
+2. Select a topic (e.g., "render.completed")
+3. Click "Send Test"
+
+The dashboard will send a test webhook with sample data:
+
+```json
+{
+  "topic": "webhook.test",
+  "data": {
+    "id": "your-api-key-id",
+    "org_id": "your-org-id"
+  }
+}
+```
+
+### 3. Verify Receipt
+
+Check your webhook endpoint logs to verify:
+- Request received
+- Signature verified successfully
+- Event processed
+
+## Unit Testing
+
+Test webhook signature verification in unit tests:
+
+```typescript
+import { describe, test, expect } from "vitest";
+import crypto from "node:crypto";
+import { verifyWebhookSignature } from "./webhooks";
+
+describe("webhook signature verification", () => {
+  const secret = "test-webhook-secret";
+
+  test("verifies valid signature", () => {
+    const payload = JSON.stringify({
+      topic: "render.completed",
+      data: { id: "test-id" }
+    });
+
+    const signature = crypto
+      .createHmac("sha256", secret)
+      .update(payload)
+      .digest("hex");
+
+    expect(verifyWebhookSignature(payload, signature, secret)).toBe(true);
+  });
+
+  test("rejects invalid signature", () => {
+    const payload = JSON.stringify({
+      topic: "render.completed",
+      data: { id: "test-id" }
+    });
+
+    const signature = "invalid-signature";
+
+    expect(verifyWebhookSignature(payload, signature, secret)).toBe(false);
+  });
+
+  test("rejects tampered payload", () => {
+    const payload = JSON.stringify({
+      topic: "render.completed",
+      data: { id: "test-id" }
+    });
+
+    const signature = crypto
+      .createHmac("sha256", secret)
+      .update(payload)
+      .digest("hex");
+
+    // Tamper with payload
+    const tamperedPayload = payload.replace("test-id", "hacked-id");
+
+    expect(verifyWebhookSignature(tamperedPayload, signature, secret)).toBe(false);
+  });
+});
+```
+
+## Integration Testing
+
+Test webhook handling end-to-end:
+
+```typescript
+import { describe, test, expect } from "vitest";
+import request from "supertest";
+import crypto from "node:crypto";
+import { app } from "./app"; // Your Express app
+
+describe("webhook endpoint", () => {
+  const secret = process.env.EDITFRAME_WEBHOOK_SECRET!;
+
+  function signPayload(payload: object): string {
+    const body = JSON.stringify(payload);
+    return crypto
+      .createHmac("sha256", secret)
+      .update(body)
+      .digest("hex");
+  }
+
+  test("accepts valid webhook", async () => {
+    const payload = {
+      topic: "render.completed",
+      data: {
+        id: "test-render-id",
+        status: "complete",
+        download_url: "https://example.com/video.mp4"
+      }
+    };
+
+    const signature = signPayload(payload);
+
+    const response = await request(app)
+      .post("/webhooks/editframe")
+      .set("X-Webhook-Signature", signature)
+      .send(payload);
+
+    expect(response.status).toBe(200);
+  });
+
+  test("rejects invalid signature", async () => {
+    const payload = {
+      topic: "render.completed",
+      data: { id: "test-id" }
+    };
+
+    const response = await request(app)
+      .post("/webhooks/editframe")
+      .set("X-Webhook-Signature", "invalid")
+      .send(payload);
+
+    expect(response.status).toBe(401);
+  });
+
+  test("rejects missing signature", async () => {
+    const payload = {
+      topic: "render.completed",
+      data: { id: "test-id" }
+    };
+
+    const response = await request(app)
+      .post("/webhooks/editframe")
+      .send(payload);
+
+    expect(response.status).toBe(401);
+  });
+});
+```
+
+## Manual Testing Script
+
+Create a script to send test webhooks:
+
+```typescript
+// scripts/send-test-webhook.ts
+import crypto from "node:crypto";
+
+const WEBHOOK_URL = "http://localhost:3000/webhooks/editframe";
+const WEBHOOK_SECRET = process.env.EDITFRAME_WEBHOOK_SECRET!;
+
+async function sendTestWebhook(topic: string, data: object) {
+  const payload = JSON.stringify({ topic, data });
+
+  const signature = crypto
+    .createHmac("sha256", WEBHOOK_SECRET)
+    .update(payload)
+    .digest("hex");
+
+  console.log(`Sending ${topic} webhook...`);
+
+  const response = await fetch(WEBHOOK_URL, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "X-Webhook-Signature": signature,
+    },
+    body: payload,
+  });
+
+  console.log(`Response: ${response.status} ${response.statusText}`);
+  console.log(await response.text());
+}
+
+// Test render.completed
+await sendTestWebhook("render.completed", {
+  id: "test-render-id",
+  status: "complete",
+  created_at: new Date().toISOString(),
+  completed_at: new Date().toISOString(),
+  failed_at: null,
+  width: 1920,
+  height: 1080,
+  fps: 30,
+  byte_size: 15728640,
+  duration_ms: 5000,
+  md5: "098f6bcd4621d373cade4e832627b4f6",
+  metadata: null,
+  download_url: "https://example.com/video.mp4"
+});
+```
+
+Run the script:
+```bash
+npx tsx scripts/send-test-webhook.ts
+```
+
+## Monitoring Webhook Logs
+
+Check webhook delivery logs in the Editframe dashboard:
+
+1. Go to your API key detail page
+2. View "Webhook Deliveries" section
+3. See:
+   - Delivery timestamp
+   - HTTP status code
+   - Response headers/body
+   - Retry attempts
+   - Success/failure status
+
+Use these logs to debug webhook issues.
+
+## Testing Checklist
+
+Before deploying to production:
+
+- [ ] Signature verification works correctly
+- [ ] Endpoint responds with 200 OK within 30 seconds
+- [ ] Invalid signatures are rejected with 401
+- [ ] Events are processed idempotently
+- [ ] Errors don't crash the server
+- [ ] Events are logged for debugging
+- [ ] Retry logic handles transient failures
+- [ ] ngrok tunnel tested successfully
+- [ ] Test webhook from dashboard works
+- [ ] Integration tests pass
+
+## Common Testing Issues
+
+### ngrok URL Not Accessible
+
+**Problem**: Webhooks aren't reaching your local server
+
+**Solution**:
+1. Check ngrok is running: `http://127.0.0.1:4040`
+2. Verify ngrok URL in API key configuration
+3. Check local server is running on correct port
+4. Check firewall settings
+
+### Signature Verification Fails
+
+**Problem**: All webhooks rejected with 401
+
+**Solution**:
+1. Verify you're using the correct webhook secret
+2. Hash the raw request body, not parsed JSON
+3. Check secret isn't corrupted (no extra spaces/newlines)
+4. Test with the manual testing script
+
+### Webhooks Not Received
+
+**Problem**: Events triggered but no webhooks received
+
+**Solution**:
+1. Check webhook URL is correct
+2. Verify webhook events are selected in API key config
+3. Check webhook delivery logs for errors
+4. Test with webhook.site to isolate issues
+
+## Next Steps
+
+- [troubleshooting.md](references/troubleshooting.md) — Debug webhook issues
+- [security.md](references/security.md) — Verify signatures correctly
+- [events.md](references/events.md) — Understand webhook payloads