@checkstack/integration-webhook-backend 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# @checkstack/integration-webhook-backend
+
+## 0.0.2
+
+### Patch Changes
+
+- d20d274: Initial release of all @checkstack packages. Rebranded from Checkmate to Checkstack with new npm organization @checkstack and domain checkstack.dev.
+- Updated dependencies [d20d274]
+  - @checkstack/backend-api@0.0.2
+  - @checkstack/common@0.0.2
+  - @checkstack/integration-backend@0.0.2
+  - @checkstack/integration-common@0.0.2
+
+## 0.1.0
+
+### Minor Changes
+
+- 4c5aa9e: Fix `IntegrationProvider.testConnection` generic type
+
+  - **Breaking**: `testConnection` now receives `TConnection` (connection config) instead of `TConfig` (subscription config)
+  - **Breaking**: `RegisteredIntegrationProvider` now includes `TConnection` generic parameter
+  - Removed `testConnection` from webhook provider (providers without `connectionSchema` cannot have `testConnection`)
+  - Fixed Jira provider to use `JiraConnectionConfig` directly in `testConnection`
+
+  This aligns the interface with the actual behavior: `testConnection` tests connection credentials, not subscription configuration.
+
+### Patch Changes
+
+- Updated dependencies [4c5aa9e]
+- Updated dependencies [b4eb432]
+- Updated dependencies [a65e002]
+- Updated dependencies [a65e002]
+  - @checkstack/integration-backend@0.1.0
+  - @checkstack/backend-api@1.1.0
+  - @checkstack/common@0.2.0
+  - @checkstack/integration-common@0.1.1
+
+## 0.0.2
+
+### Patch Changes
+
+- Updated dependencies [ffc28f6]
+- Updated dependencies [4dd644d]
+- Updated dependencies [71275dd]
+- Updated dependencies [ae19ff6]
+- Updated dependencies [b55fae6]
+- Updated dependencies [b354ab3]
+- Updated dependencies [81f3f85]
+  - @checkstack/common@0.1.0
+  - @checkstack/backend-api@1.0.0
+  - @checkstack/integration-common@0.1.0
+  - @checkstack/integration-backend@0.0.2

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@checkstack/integration-webhook-backend",
+  "version": "0.0.2",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  },
+  "dependencies": {
+    "@checkstack/backend-api": "workspace:*",
+    "@checkstack/integration-backend": "workspace:*",
+    "@checkstack/integration-common": "workspace:*",
+    "@checkstack/common": "workspace:*",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.0.0",
+    "typescript": "^5.0.0",
+    "@checkstack/tsconfig": "workspace:*",
+    "@checkstack/scripts": "workspace:*"
+  }
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+import {
+  createBackendPlugin,
+  coreServices,
+} from "@checkstack/backend-api";
+import { integrationProviderExtensionPoint } from "@checkstack/integration-backend";
+import { pluginMetadata } from "./plugin-metadata";
+import { webhookProvider } from "./provider";
+
+export default createBackendPlugin({
+  metadata: pluginMetadata,
+
+  register(env) {
+    env.registerInit({
+      deps: {
+        logger: coreServices.logger,
+      },
+      init: async ({ logger }) => {
+        logger.debug("🔌 Registering Webhook Integration Provider...");
+
+        // Get the integration provider extension point
+        const extensionPoint = env.getExtensionPoint(
+          integrationProviderExtensionPoint
+        );
+
+        // Register the webhook provider
+        extensionPoint.addProvider(webhookProvider, pluginMetadata);
+
+        logger.debug("✅ Webhook Integration Provider registered.");
+      },
+    });
+  },
+});

package/src/plugin-metadata.ts

@@ -0,0 +1,9 @@
+import { definePluginMetadata } from "@checkstack/common";
+
+/**
+ * Plugin metadata for the Webhook Integration Provider.
+ * This is the single source of truth for the plugin ID.
+ */
+export const pluginMetadata = definePluginMetadata({
+  pluginId: "integration-webhook",
+});

package/src/provider.test.ts

@@ -0,0 +1,513 @@
+import { describe, it, expect, beforeEach, mock, spyOn } from "bun:test";
+import {
+  webhookProvider,
+  webhookConfigSchemaV1,
+  type WebhookConfig,
+} from "./provider";
+import type { IntegrationDeliveryContext } from "@checkstack/integration-backend";
+
+/**
+ * Unit tests for the Webhook Integration Provider.
+ *
+ * Tests cover:
+ * - Config schema validation
+ * - Successful webhook delivery
+ * - Authentication methods (bearer, basic, header)
+ * - Error handling and retry logic
+ * - Test connection functionality
+ */
+
+// Mock logger
+const mockLogger = {
+  debug: mock(() => {}),
+  info: mock(() => {}),
+  warn: mock(() => {}),
+  error: mock(() => {}),
+};
+
+// Create a test delivery context
+function createTestContext(
+  configOverrides: Partial<WebhookConfig> = {}
+): IntegrationDeliveryContext<WebhookConfig> {
+  const defaultConfig: WebhookConfig = {
+    url: "https://example.com/webhook",
+    method: "POST",
+    contentType: "application/json",
+    authType: "none",
+    timeout: 10_000,
+    ...configOverrides,
+  };
+
+  return {
+    event: {
+      eventId: "test-plugin.incident.created",
+      payload: { incidentId: "inc-123", severity: "critical" },
+      timestamp: new Date().toISOString(),
+      deliveryId: "del-456",
+    },
+    subscription: {
+      id: "sub-789",
+      name: "Test Subscription",
+    },
+    providerConfig: defaultConfig,
+    logger: mockLogger,
+  };
+}
+
+describe("WebhookProvider", () => {
+  beforeEach(() => {
+    mockLogger.debug.mockClear();
+    mockLogger.info.mockClear();
+    mockLogger.warn.mockClear();
+    mockLogger.error.mockClear();
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Provider Metadata
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("metadata", () => {
+    it("has correct basic metadata", () => {
+      expect(webhookProvider.id).toBe("webhook");
+      expect(webhookProvider.displayName).toBe("Webhook");
+      expect(webhookProvider.description).toContain("HTTP POST");
+      expect(webhookProvider.icon).toBe("Webhook");
+    });
+
+    it("has a versioned config schema", () => {
+      expect(webhookProvider.config).toBeDefined();
+      expect(webhookProvider.config.version).toBe(1);
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Config Schema Validation
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("config schema", () => {
+    it("requires valid URL", () => {
+      expect(() => {
+        webhookConfigSchemaV1.parse({
+          url: "not-a-url",
+        });
+      }).toThrow();
+    });
+
+    it("accepts valid URL", () => {
+      const result = webhookConfigSchemaV1.parse({
+        url: "https://example.com/webhook",
+      });
+      expect(result.url).toBe("https://example.com/webhook");
+    });
+
+    it("applies default values", () => {
+      const result = webhookConfigSchemaV1.parse({
+        url: "https://example.com/webhook",
+      });
+
+      expect(result.method).toBe("POST");
+      expect(result.contentType).toBe("application/json");
+      expect(result.authType).toBe("none");
+      expect(result.timeout).toBe(10_000);
+    });
+
+    it("validates method enum", () => {
+      expect(() => {
+        webhookConfigSchemaV1.parse({
+          url: "https://example.com",
+          method: "DELETE", // Not allowed
+        });
+      }).toThrow();
+    });
+
+    it("allows valid methods", () => {
+      for (const method of ["POST", "PUT", "PATCH"] as const) {
+        const result = webhookConfigSchemaV1.parse({
+          url: "https://example.com",
+          method,
+        });
+        expect(result.method).toBe(method);
+      }
+    });
+
+    it("validates timeout range", () => {
+      expect(() => {
+        webhookConfigSchemaV1.parse({
+          url: "https://example.com",
+          timeout: 500, // Too short
+        });
+      }).toThrow();
+
+      expect(() => {
+        webhookConfigSchemaV1.parse({
+          url: "https://example.com",
+          timeout: 100_000, // Too long
+        });
+      }).toThrow();
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Delivery - Basic
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("deliver - basic", () => {
+    it("makes HTTP request with correct payload structure", async () => {
+      let capturedBody: string | undefined;
+      let capturedHeaders: Record<string, string> | undefined;
+
+      const mockFetch = spyOn(globalThis, "fetch").mockImplementation((async (
+        _url: RequestInfo | URL,
+        options?: RequestInit
+      ) => {
+        capturedBody = options?.body as string;
+        capturedHeaders = options?.headers as Record<string, string>;
+        return new Response(JSON.stringify({ ok: true }), { status: 200 });
+      }) as unknown as typeof fetch);
+
+      try {
+        const context = createTestContext();
+        const result = await webhookProvider.deliver(context);
+
+        expect(result.success).toBe(true);
+        expect(capturedBody).toBeDefined();
+
+        const parsedBody = JSON.parse(capturedBody!);
+        expect(parsedBody.id).toBe("del-456");
+        expect(parsedBody.eventType).toBe("test-plugin.incident.created");
+        expect(parsedBody.subscription.id).toBe("sub-789");
+        expect(parsedBody.data).toEqual({
+          incidentId: "inc-123",
+          severity: "critical",
+        });
+
+        expect(capturedHeaders?.["Content-Type"]).toBe("application/json");
+        expect(capturedHeaders?.["X-Delivery-Id"]).toBe("del-456");
+        expect(capturedHeaders?.["X-Event-Type"]).toBe(
+          "test-plugin.incident.created"
+        );
+      } finally {
+        mockFetch.mockRestore();
+      }
+    });
+
+    it("returns external ID from response if present", async () => {
+      const mockFetch = spyOn(globalThis, "fetch").mockImplementation(
+        (async () => {
+          return new Response(JSON.stringify({ id: "external-id-123" }), {
+            status: 200,
+          });
+        }) as unknown as typeof fetch
+      );
+
+      try {
+        const context = createTestContext();
+        const result = await webhookProvider.deliver(context);
+
+        expect(result.success).toBe(true);
+        expect(result.externalId).toBe("external-id-123");
+      } finally {
+        mockFetch.mockRestore();
+      }
+    });
+
+    it("handles non-JSON response gracefully", async () => {
+      const mockFetch = spyOn(globalThis, "fetch").mockImplementation(
+        (async () => {
+          return new Response("OK", { status: 200 });
+        }) as unknown as typeof fetch
+      );
+
+      try {
+        const context = createTestContext();
+        const result = await webhookProvider.deliver(context);
+
+        expect(result.success).toBe(true);
+        expect(result.externalId).toBeUndefined();
+      } finally {
+        mockFetch.mockRestore();
+      }
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Delivery - Authentication
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("deliver - authentication", () => {
+    it("adds Bearer token header", async () => {
+      let capturedHeaders: Record<string, string> | undefined;
+
+      const mockFetch = spyOn(globalThis, "fetch").mockImplementation((async (
+        _url: RequestInfo | URL,
+        options?: RequestInit
+      ) => {
+        capturedHeaders = options?.headers as Record<string, string>;
+        return new Response("OK", { status: 200 });
+      }) as unknown as typeof fetch);
+
+      try {
+        const context = createTestContext({
+          authType: "bearer",
+          bearerToken: "my-secret-token",
+        });
+        await webhookProvider.deliver(context);
+
+        expect(capturedHeaders?.["Authorization"]).toBe(
+          "Bearer my-secret-token"
+        );
+      } finally {
+        mockFetch.mockRestore();
+      }
+    });
+
+    it("adds Basic auth header", async () => {
+      let capturedHeaders: Record<string, string> | undefined;
+
+      const mockFetch = spyOn(globalThis, "fetch").mockImplementation((async (
+        _url: RequestInfo | URL,
+        options?: RequestInit
+      ) => {
+        capturedHeaders = options?.headers as Record<string, string>;
+        return new Response("OK", { status: 200 });
+      }) as unknown as typeof fetch);
+
+      try {
+        const context = createTestContext({
+          authType: "basic",
+          basicUsername: "user",
+          basicPassword: "pass",
+        });
+        await webhookProvider.deliver(context);
+
+        // user:pass in base64
+        const expectedAuth = `Basic ${Buffer.from("user:pass").toString(
+          "base64"
+        )}`;
+        expect(capturedHeaders?.["Authorization"]).toBe(expectedAuth);
+      } finally {
+        mockFetch.mockRestore();
+      }
+    });
+
+    it("adds custom auth header", async () => {
+      let capturedHeaders: Record<string, string> | undefined;
+
+      const mockFetch = spyOn(globalThis, "fetch").mockImplementation((async (
+        _url: RequestInfo | URL,
+        options?: RequestInit
+      ) => {
+        capturedHeaders = options?.headers as Record<string, string>;
+        return new Response("OK", { status: 200 });
+      }) as unknown as typeof fetch);
+
+      try {
+        const context = createTestContext({
+          authType: "header",
+          authHeaderName: "X-API-Key",
+          authHeaderValue: "api-key-123",
+        });
+        await webhookProvider.deliver(context);
+
+        expect(capturedHeaders?.["X-API-Key"]).toBe("api-key-123");
+      } finally {
+        mockFetch.mockRestore();
+      }
+    });
+
+    it("adds custom headers", async () => {
+      let capturedHeaders: Record<string, string> | undefined;
+
+      const mockFetch = spyOn(globalThis, "fetch").mockImplementation((async (
+        _url: RequestInfo | URL,
+        options?: RequestInit
+      ) => {
+        capturedHeaders = options?.headers as Record<string, string>;
+        return new Response("OK", { status: 200 });
+      }) as unknown as typeof fetch);
+
+      try {
+        const context = createTestContext({
+          customHeaders: [
+            { name: "X-Custom-Header", value: "custom-value" },
+            { name: "X-Another-Header", value: "another-value" },
+          ],
+        });
+        await webhookProvider.deliver(context);
+
+        expect(capturedHeaders?.["X-Custom-Header"]).toBe("custom-value");
+        expect(capturedHeaders?.["X-Another-Header"]).toBe("another-value");
+      } finally {
+        mockFetch.mockRestore();
+      }
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Delivery - Error Handling
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("deliver - error handling", () => {
+    it("returns error for non-OK response", async () => {
+      const mockFetch = spyOn(globalThis, "fetch").mockImplementation(
+        (async () => {
+          return new Response("Not Found", { status: 404 });
+        }) as unknown as typeof fetch
+      );
+
+      try {
+        const context = createTestContext();
+        const result = await webhookProvider.deliver(context);
+
+        expect(result.success).toBe(false);
+        expect(result.error).toContain("404");
+      } finally {
+        mockFetch.mockRestore();
+      }
+    });
+
+    it("returns retryable error for configured status codes", async () => {
+      const mockFetch = spyOn(globalThis, "fetch").mockImplementation(
+        (async () => {
+          return new Response("Too Many Requests", { status: 429 });
+        }) as unknown as typeof fetch
+      );
+
+      try {
+        const context = createTestContext({
+          retryOnStatus: [429, 503],
+        });
+        const result = await webhookProvider.deliver(context);
+
+        expect(result.success).toBe(false);
+        expect(result.error).toContain("retryable");
+        expect(result.retryAfterMs).toBeDefined();
+      } finally {
+        mockFetch.mockRestore();
+      }
+    });
+
+    it("parses Retry-After header", async () => {
+      const mockFetch = spyOn(globalThis, "fetch").mockImplementation(
+        (async () => {
+          const headers = new Headers();
+          headers.set("Retry-After", "60");
+          return new Response("Too Many Requests", {
+            status: 429,
+            headers,
+          });
+        }) as unknown as typeof fetch
+      );
+
+      try {
+        const context = createTestContext({
+          retryOnStatus: [429],
+        });
+        const result = await webhookProvider.deliver(context);
+
+        expect(result.retryAfterMs).toBe(60_000);
+      } finally {
+        mockFetch.mockRestore();
+      }
+    });
+
+    it("handles network errors with retry", async () => {
+      const mockFetch = spyOn(globalThis, "fetch").mockImplementation(
+        (async () => {
+          throw new Error("ECONNREFUSED");
+        }) as unknown as typeof fetch
+      );
+
+      try {
+        const context = createTestContext();
+        const result = await webhookProvider.deliver(context);
+
+        expect(result.success).toBe(false);
+        expect(result.error).toContain("ECONNREFUSED");
+        expect(result.retryAfterMs).toBe(30_000);
+      } finally {
+        mockFetch.mockRestore();
+      }
+    });
+
+    it("handles timeout errors with retry", async () => {
+      const mockFetch = spyOn(globalThis, "fetch").mockImplementation(
+        (async () => {
+          throw new Error("timeout");
+        }) as unknown as typeof fetch
+      );
+
+      try {
+        const context = createTestContext();
+        const result = await webhookProvider.deliver(context);
+
+        expect(result.success).toBe(false);
+        expect(result.retryAfterMs).toBe(30_000);
+      } finally {
+        mockFetch.mockRestore();
+      }
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Content Types
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("content types", () => {
+    it("sends JSON body for application/json", async () => {
+      let capturedBody: string | undefined;
+      let capturedContentType: string | undefined;
+
+      const mockFetch = spyOn(globalThis, "fetch").mockImplementation((async (
+        _url: RequestInfo | URL,
+        options?: RequestInit
+      ) => {
+        capturedBody = options?.body as string;
+        capturedContentType = (options?.headers as Record<string, string>)?.[
+          "Content-Type"
+        ];
+        return new Response("OK", { status: 200 });
+      }) as unknown as typeof fetch);
+
+      try {
+        const context = createTestContext({
+          contentType: "application/json",
+        });
+        await webhookProvider.deliver(context);
+
+        expect(capturedContentType).toBe("application/json");
+        expect(() => JSON.parse(capturedBody!)).not.toThrow();
+      } finally {
+        mockFetch.mockRestore();
+      }
+    });
+
+    it("sends form-encoded body for application/x-www-form-urlencoded", async () => {
+      let capturedBody: string | undefined;
+      let capturedContentType: string | undefined;
+
+      const mockFetch = spyOn(globalThis, "fetch").mockImplementation((async (
+        _url: RequestInfo | URL,
+        options?: RequestInit
+      ) => {
+        capturedBody = options?.body as string;
+        capturedContentType = (options?.headers as Record<string, string>)?.[
+          "Content-Type"
+        ];
+        return new Response("OK", { status: 200 });
+      }) as unknown as typeof fetch);
+
+      try {
+        const context = createTestContext({
+          contentType: "application/x-www-form-urlencoded",
+        });
+        await webhookProvider.deliver(context);
+
+        expect(capturedContentType).toBe("application/x-www-form-urlencoded");
+        expect(capturedBody).toContain("payload=");
+      } finally {
+        mockFetch.mockRestore();
+      }
+    });
+  });
+});

package/src/provider.ts

@@ -0,0 +1,347 @@
+import { z } from "zod";
+import {
+  Versioned,
+  configNumber,
+  configString,
+} from "@checkstack/backend-api";
+import type {
+  IntegrationProvider,
+  IntegrationDeliveryContext,
+  IntegrationDeliveryResult,
+} from "@checkstack/integration-backend";
+
+// =============================================================================
+// Template Expansion Helper
+// =============================================================================
+
+/**
+ * Expand mustache-style templates with context values.
+ * Supports {{path.to.value}} syntax with nested object access.
+ */
+function expandTemplate(
+  template: string,
+  context: Record<string, unknown>
+): string {
+  return template.replaceAll(/\{\{([^}]+)\}\}/g, (_match, path: string) => {
+    const trimmedPath = path.trim();
+    const parts = trimmedPath.split(".");
+
+    let value: unknown = context;
+    for (const part of parts) {
+      if (value === null || value === undefined) {
+        return "";
+      }
+      value = (value as Record<string, unknown>)[part];
+    }
+
+    // Return JSON stringified for objects/arrays, raw string for primitives
+    if (value === null || value === undefined) {
+      return "";
+    }
+    if (typeof value === "object") {
+      return JSON.stringify(value);
+    }
+    return String(value);
+  });
+}
+
+// =============================================================================
+// Webhook Configuration Schema
+// =============================================================================
+
+/**
+ * Header configuration for custom HTTP headers.
+ */
+const webhookHeaderSchema = z.object({
+  name: z.string().min(1).describe("Header name"),
+  value: z.string().describe("Header value"),
+});
+
+/**
+ * Webhook provider configuration schema.
+ * Supports various authentication methods and customization options.
+ */
+export const webhookConfigSchemaV1 = z.object({
+  url: configString({})
+    .url()
+    .describe("The webhook endpoint URL to send events to"),
+  method: z
+    .enum(["POST", "PUT", "PATCH"])
+    .default("POST")
+    .describe("HTTP method to use"),
+  contentType: z
+    .enum(["application/json", "application/x-www-form-urlencoded"])
+    .default("application/json")
+    .describe("Content-Type header for the request"),
+
+  // Authentication
+  authType: z
+    .enum(["none", "bearer", "basic", "header"])
+    .default("none")
+    .describe("Authentication method"),
+  bearerToken: configString({ "x-secret": true })
+    .describe("Bearer token for authentication")
+    .optional(),
+  basicUsername: configString({})
+    .optional()
+    .describe("Username for Basic auth"),
+  basicPassword: configString({ "x-secret": true })
+    .describe("Password for Basic auth")
+    .optional(),
+  authHeaderName: configString({})
+    .optional()
+    .describe("Custom header name for token auth (e.g., X-API-Key)"),
+  authHeaderValue: configString({ "x-secret": true })
+    .describe("Custom header value")
+    .optional(),
+
+  // Additional options
+  customHeaders: z
+    .array(webhookHeaderSchema)
+    .optional()
+    .describe("Additional custom headers to include"),
+
+  /** Custom body template. Use {{payload.field}} syntax for templating. */
+  bodyTemplate: configString({})
+    .optional()
+    .describe(
+      "Custom request body template. Use {{payload.field}} syntax to include event data. Leave empty for default JSON payload."
+    ),
+
+  timeout: configNumber({})
+    .min(1000)
+    .max(60_000)
+    .default(10_000)
+    .describe("Request timeout in milliseconds"),
+  retryOnStatus: z
+    .array(configNumber({}))
+    .optional()
+    .describe("HTTP status codes that should trigger a retry (e.g., 429, 503)"),
+});
+
+export type WebhookConfig = z.infer<typeof webhookConfigSchemaV1>;
+
+// =============================================================================
+// Webhook Provider Implementation
+// =============================================================================
+
+/**
+ * Webhook integration provider.
+ * Delivers events as HTTP POST requests to configured endpoints.
+ */
+export const webhookProvider: IntegrationProvider<WebhookConfig> = {
+  id: "webhook",
+  displayName: "Webhook",
+  description: "Deliver events via HTTP POST to external endpoints",
+  icon: "Webhook",
+
+  config: new Versioned({
+    version: 1,
+    schema: webhookConfigSchemaV1,
+  }),
+
+  documentation: {
+    setupGuide: `Your endpoint will receive HTTP POST requests with JSON payloads.
+
+Configure your server to:
+1. Accept POST requests at your configured URL
+2. Return a 2xx status code on success
+3. Optionally return a JSON response with an \`id\` field for tracking`,
+    examplePayload: JSON.stringify(
+      {
+        id: "del_abc123",
+        eventType: "incident.created",
+        timestamp: "2024-01-15T10:30:00.000Z",
+        subscription: {
+          id: "sub_xyz",
+          name: "My Webhook",
+        },
+        data: {
+          incidentId: "inc_123",
+          title: "API degraded performance",
+          severity: "warning",
+        },
+      },
+      // eslint-disable-next-line unicorn/no-null
+      null,
+      2
+    ),
+    headers: [
+      {
+        name: "Content-Type",
+        description: "application/json (or application/x-www-form-urlencoded)",
+      },
+      {
+        name: "X-Delivery-Id",
+        description: "Unique ID for this delivery attempt",
+      },
+      {
+        name: "X-Event-Type",
+        description: "The event type (e.g., incident.created)",
+      },
+      { name: "User-Agent", description: "Checkstack-Integration/1.0" },
+    ],
+  },
+
+  async deliver(
+    context: IntegrationDeliveryContext<WebhookConfig>
+  ): Promise<IntegrationDeliveryResult> {
+    const { event, subscription, providerConfig, logger } = context;
+
+    // Validate config
+    const config = webhookConfigSchemaV1.parse(providerConfig);
+
+    // Build template context for all template-able fields
+    const templateContext = {
+      deliveryId: event.deliveryId,
+      eventType: event.eventId,
+      eventId: event.eventId,
+      timestamp: event.timestamp,
+      subscriptionId: subscription.id,
+      subscriptionName: subscription.name,
+      payload: event.payload,
+    };
+
+    // Expand URL template if it contains template syntax
+    const url = expandTemplate(config.url, templateContext);
+
+    // Build headers
+    const headers: Record<string, string> = {
+      "Content-Type": config.contentType,
+      "User-Agent": "Checkstack-Integration/1.0",
+      "X-Delivery-Id": event.deliveryId,
+      "X-Event-Type": event.eventId,
+    };
+
+    // Add authentication headers
+    switch (config.authType) {
+      case "bearer": {
+        if (config.bearerToken) {
+          headers["Authorization"] = `Bearer ${config.bearerToken}`;
+        }
+        break;
+      }
+      case "basic": {
+        if (config.basicUsername && config.basicPassword) {
+          const credentials = Buffer.from(
+            `${config.basicUsername}:${config.basicPassword}`
+          ).toString("base64");
+          headers["Authorization"] = `Basic ${credentials}`;
+        }
+        break;
+      }
+      case "header": {
+        if (config.authHeaderName && config.authHeaderValue) {
+          headers[config.authHeaderName] = config.authHeaderValue;
+        }
+        break;
+      }
+    }
+
+    // Add custom headers (with template expansion)
+    if (config.customHeaders) {
+      for (const header of config.customHeaders) {
+        headers[header.name] = expandTemplate(header.value, templateContext);
+      }
+    }
+
+    // Build request body
+    let body: string;
+
+    if (config.bodyTemplate) {
+      // Use custom template with context
+      body = expandTemplate(config.bodyTemplate, templateContext);
+    } else {
+      // Default payload format
+      const payload = {
+        id: event.deliveryId,
+        eventType: event.eventId,
+        timestamp: event.timestamp,
+        subscription: {
+          id: subscription.id,
+          name: subscription.name,
+        },
+        data: event.payload,
+      };
+
+      body =
+        config.contentType === "application/json"
+          ? JSON.stringify(payload)
+          : new URLSearchParams({
+              payload: JSON.stringify(payload),
+            }).toString();
+    }
+
+    logger.debug(`Delivering webhook to ${url} for event ${event.eventId}`);
+
+    try {
+      const response = await fetch(url, {
+        method: config.method,
+        headers,
+        body,
+        signal: AbortSignal.timeout(config.timeout),
+      });
+
+      const responseText = await response.text();
+
+      // Check if we should retry based on status code
+      if (config.retryOnStatus?.includes(response.status)) {
+        // Check for Retry-After header
+        const retryAfter = response.headers.get("Retry-After");
+        const retryAfterMs = retryAfter
+          ? Number.parseInt(retryAfter, 10) * 1000
+          : 30_000;
+
+        return {
+          success: false,
+          error: `Received status ${response.status} (retryable)`,
+          retryAfterMs,
+        };
+      }
+
+      if (!response.ok) {
+        return {
+          success: false,
+          error: `HTTP ${response.status}: ${responseText.slice(0, 200)}`,
+        };
+      }
+
+      logger.debug(`Webhook delivered successfully: ${response.status}`);
+
+      // Try to extract external ID from response
+      let externalId: string | undefined;
+      try {
+        const json = JSON.parse(responseText);
+        externalId = json.id ?? json.externalId ?? json.messageId;
+      } catch {
+        // Response wasn't JSON, that's fine
+      }
+
+      return {
+        success: true,
+        externalId,
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      logger.error(`Webhook delivery failed: ${message}`);
+
+      // Network errors should trigger retry
+      if (
+        message.includes("timeout") ||
+        message.includes("ECONNREFUSED") ||
+        message.includes("ENOTFOUND")
+      ) {
+        return {
+          success: false,
+          error: message,
+          retryAfterMs: 30_000,
+        };
+      }
+
+      return {
+        success: false,
+        error: message,
+      };
+    }
+  },
+};

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@checkstack/tsconfig/backend.json",
+  "include": [
+    "src"
+  ]
+}