@ampless/plugin-webhook 0.2.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ampless contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# @ampless/plugin-webhook
+
+POST ampless events to one or more external URLs.
+
+> **Pre-release / alpha.** Breaking changes possible in any minor version until v1.0.
+
+Runs in the **untrusted** Lambda — it makes outbound HTTPS calls and never touches AWS data, so a compromised webhook receiver can't pivot into your CMS.
+
+## Install
+
+```bash
+npm install @ampless/plugin-webhook@alpha
+```
+
+## Configure
+
+In `cms.config.ts`:
+
+```ts
+import webhookPlugin from '@ampless/plugin-webhook'
+
+export default defineConfig({
+  // ...
+  plugins: [
+    webhookPlugin({
+      endpoints: [
+        {
+          url: 'https://example.com/hooks/ampless',
+          secret: process.env.WEBHOOK_SECRET,
+          events: ['content.published', 'content.unpublished', 'content.deleted'],
+        },
+        {
+          url: 'https://discord.com/api/webhooks/.../...',
+          // No secret — Discord doesn't verify signatures
+          events: ['content.published'],
+        },
+      ],
+    }),
+  ],
+})
+```
+
+| Option | Default | Notes |
+|---|---|---|
+| `endpoints[].url` | required | HTTPS endpoint to POST to |
+| `endpoints[].secret` | none | When set, body is HMAC-SHA-256 signed; sent in `X-Ampless-Signature` |
+| `endpoints[].events` | all `content.*` | Restrict which event types fire this endpoint |
+| `endpoints[].headers` | `{}` | Extra headers merged into every request |
+| `endpoints[].timeoutMs` | `5000` | Per-request timeout |
+| `url` (top-level) | none | Single-endpoint shortcut, equivalent to `endpoints: [{ url, secret }]` |
+| `secret` (top-level) | none | Pairs with the top-level `url` |
+
+## Request shape
+
+```http
+POST /hooks/ampless HTTP/1.1
+Host: example.com
+Content-Type: application/json
+X-Ampless-Event: content.published
+X-Ampless-Signature: sha256=<hex>
+
+{
+  "type": "content.published",
+  "payload": {
+    "siteId": "default",
+    "postId": "post-001",
+    "slug": "hello",
+    "title": "Hello",
+    "status": "published",
+    "publishedAt": "2026-04-30T00:00:00.000Z",
+    "tags": ["intro"]
+  },
+  "timestamp": "2026-04-30T00:00:01.000Z"
+}
+```
+
+## Verifying the signature (Node.js)
+
+```ts
+import { createHmac, timingSafeEqual } from 'node:crypto'
+
+function verify(rawBody: string, signatureHeader: string, secret: string): boolean {
+  const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex')
+  const a = Buffer.from(expected)
+  const b = Buffer.from(signatureHeader)
+  if (a.length !== b.length) return false
+  return timingSafeEqual(a, b)
+}
+```
+
+Always compute the HMAC over the **raw request body** before any JSON parsing, and use a constant-time comparison.
+
+## Retry behavior
+
+When any endpoint returns a non-2xx response (or times out), the plugin throws. The trust-level processor Lambda re-throws to SQS, which retries the message up to 3 times before moving it to the dead-letter queue. Idempotent receivers are recommended — the same event can be delivered more than once.
+
+## Events emitted
+
+- `content.created` — new post (any status)
+- `content.published` — status went `draft` → `published`, or a published post was inserted
+- `content.unpublished` — status went `published` → `draft`, or a published post was deleted
+- `content.updated` — any MODIFY (also fires alongside published/unpublished on transitions)
+- `content.deleted` — post removed

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+import { EventType, AmplessPlugin } from 'ampless';
+
+/**
+ * HMAC SHA-256 signature in the format `sha256=<hex>`. Receivers verify
+ * by recomputing the HMAC over the raw request body and constant-time
+ * comparing against the header value (same conventions as GitHub
+ * webhooks, Stripe, etc.).
+ */
+declare function signPayload(secret: string, body: string): string;
+
+interface WebhookEndpoint {
+    /** Target URL. Required. */
+    url: string;
+    /**
+     * Optional shared secret. When set, the body is HMAC-SHA-256 signed and
+     * the result is sent in the `X-Ampless-Signature` header (format:
+     * `sha256=<hex>`). Receivers should constant-time compare against the
+     * recomputed HMAC over the raw body to authenticate.
+     */
+    secret?: string;
+    /**
+     * Restrict which events fire this endpoint. Omit to receive all
+     * supported event types (currently the content.* family).
+     */
+    events?: EventType[];
+    /** Extra headers merged into every request to this endpoint. */
+    headers?: Record<string, string>;
+    /** Per-request timeout in ms. Default 5000. */
+    timeoutMs?: number;
+}
+interface WebhookPluginOptions {
+    endpoints?: WebhookEndpoint[];
+    /** Backwards-compatible single-endpoint shortcut. */
+    url?: string;
+    secret?: string;
+}
+/**
+ * Webhook plugin. Posts a JSON envelope to one or more external URLs
+ * whenever a subscribed event fires. Runs in the untrusted Lambda — it
+ * needs no AWS data access, only outbound HTTPS.
+ */
+declare function webhookPlugin(options?: WebhookPluginOptions): AmplessPlugin;
+
+export { type WebhookEndpoint, type WebhookPluginOptions, webhookPlugin as default, signPayload };

package/dist/index.js

@@ -0,0 +1,87 @@
+// src/index.ts
+import { definePlugin } from "ampless";
+
+// src/sign.ts
+import { createHmac } from "crypto";
+function signPayload(secret, body) {
+  return "sha256=" + createHmac("sha256", secret).update(body).digest("hex");
+}
+
+// src/index.ts
+var ALL_CONTENT_EVENTS = [
+  "content.created",
+  "content.updated",
+  "content.published",
+  "content.unpublished",
+  "content.deleted"
+];
+function webhookPlugin(options = {}) {
+  const endpoints = normalizeEndpoints(options);
+  const subscribed = /* @__PURE__ */ new Set();
+  for (const ep of endpoints) {
+    const events = ep.events ?? ALL_CONTENT_EVENTS;
+    events.forEach((e) => subscribed.add(e));
+  }
+  const hooks = {};
+  for (const eventType of subscribed) {
+    hooks[eventType] = async (event) => {
+      await dispatch(endpoints, event);
+    };
+  }
+  return definePlugin({
+    name: "webhook",
+    apiVersion: 1,
+    trust_level: "untrusted",
+    hooks
+  });
+}
+function normalizeEndpoints(options) {
+  const list = [];
+  if (options.url) list.push({ url: options.url, secret: options.secret });
+  if (options.endpoints) list.push(...options.endpoints);
+  return list;
+}
+async function dispatch(endpoints, event) {
+  const body = JSON.stringify({
+    type: event.type,
+    payload: event.payload,
+    timestamp: event.timestamp
+  });
+  const results = await Promise.allSettled(
+    endpoints.filter((ep) => (ep.events ?? ALL_CONTENT_EVENTS).includes(event.type)).map((ep) => postOne(ep, body, event.type))
+  );
+  const failures = results.filter((r) => r.status === "rejected");
+  if (failures.length > 0) {
+    const messages = failures.map((f) => String(f.reason)).join("; ");
+    throw new Error(`webhook plugin: ${failures.length} endpoint(s) failed \u2014 ${messages}`);
+  }
+}
+async function postOne(endpoint, body, eventType) {
+  const headers = {
+    "Content-Type": "application/json",
+    "X-Ampless-Event": eventType,
+    ...endpoint.headers ?? {}
+  };
+  if (endpoint.secret) {
+    headers["X-Ampless-Signature"] = signPayload(endpoint.secret, body);
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), endpoint.timeoutMs ?? 5e3);
+  try {
+    const response = await fetch(endpoint.url, {
+      method: "POST",
+      headers,
+      body,
+      signal: controller.signal
+    });
+    if (!response.ok) {
+      throw new Error(`${endpoint.url} returned ${response.status}`);
+    }
+  } finally {
+    clearTimeout(timer);
+  }
+}
+export {
+  webhookPlugin as default,
+  signPayload
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@ampless/plugin-webhook",
+  "version": "0.2.0-alpha.0",
+  "description": "Webhook plugin for ampless — POST events to external URLs",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/heavymoons/ampless.git",
+    "directory": "packages/plugin-webhook"
+  },
+  "homepage": "https://github.com/heavymoons/ampless/tree/main/packages/plugin-webhook#readme",
+  "bugs": "https://github.com/heavymoons/ampless/issues",
+  "dependencies": {
+    "ampless": "0.2.0-alpha.0"
+  },
+  "keywords": [
+    "ampless",
+    "plugin",
+    "webhook"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
+}