@shivaedev/webhooks 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ShivaeDev
+
+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

@@ -1,3 +1,115 @@
-# Temporary Holding Version
+# @shivaedev/webhooks
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Receive signed webhooks without building signature checks, delivery deduplication and receipt logging in every application. One route records a delivery and queues its work atomically; your workers own the feature.
+
+## Receive once, work in queues
+
+A sender can retry or send concurrent copies. Your application declares which events become jobs, and the inbox queues them once per source and delivery ID.
+
+```ts
+const sources = {
+  github: githubSource({
+    key: Config.Redacted("GITHUB_WEBHOOK_SECRET"),
+    events: {
+      issues: webhookEvent(IssueEvent, ({ issue }) => [
+        webhookJob(IndexIssue, { number: issue.number }),
+      ]),
+    },
+  }),
+};
+```
+
+## Using the inbox
+
+A source has a name, a verification strategy, a signing key loaded through Effect Config, and event registrations. Strategies read delivery identity and event names from headers and verify the raw bytes before JSON decoding. Event schemas describe only the fields your application needs; the mapping returns typed job requests. No worker handler runs in the route.
+
+### Register receipts and queues
+
+Register `webhookReceipts` in the host's `migrations.components` alongside `pgBossSchema()`. The normal migration mode applies it; `check` reports a missing component, and `wait` waits for it. The receipt table is `webhook_receipts`, keyed by `(source, delivery_id)`, with the event, a UTC `timestamptz` received time, `queued` or `ignored` outcome, and a JSON array of queued job IDs.
+
+```ts
+import { Config, Effect, Layer, Redacted, Schema } from "effect";
+import { SqlClient } from "effect/sql";
+import { defineQueue } from "@shivaedev/jobs/server/definition.ts";
+import { pgBossSchema } from "@shivaedev/jobs/server/schema.ts";
+import { makePgBoss } from "@shivaedev/jobs/server/service.ts";
+import { appHost } from "@shivaedev/server/appHost.ts";
+import { githubSource } from "@shivaedev/webhooks/github.ts";
+import { webhookEvent, webhookJob } from "@shivaedev/webhooks/registration.ts";
+import { webhookRoute } from "@shivaedev/webhooks/route.ts";
+import { webhookReceipts } from "@shivaedev/webhooks/webhookReceipts.ts";
+
+const Jobs = makePgBoss("app/Jobs");
+const IndexIssue = defineQueue({
+  name: "index-issue",
+  schema: Schema.Struct({ number: Schema.Number }),
+});
+const IssueEvent = Schema.Struct({
+  issue: Schema.Struct({ number: Schema.Number }),
+});
+const sources = {
+  github: githubSource({
+    key: Config.Redacted("GITHUB_WEBHOOK_SECRET"),
+    events: {
+      issues: webhookEvent(IssueEvent, ({ issue }) => [
+        webhookJob(IndexIssue, { number: issue.number }),
+      ]),
+    },
+  }),
+};
+
+const Host = appHost({
+  config: { databaseUrl },
+  migrations: {
+    loader,
+    components: [pgBossSchema(), webhookReceipts],
+  },
+  application: Effect.gen(function* () {
+    const sql = yield* SqlClient.SqlClient;
+    const jobs = Jobs.layer({
+      connectionString: Redacted.value(databaseUrl),
+      jobs: [IndexIssue],
+      migrate: false,
+    });
+    return {
+      group: Api,
+      handlers,
+      sessions,
+      services: jobs,
+      routes: webhookRoute({ basePath: "/webhooks", jobs: Jobs, sources }).pipe(
+        Layer.provide(jobs),
+        Layer.provide(Layer.succeed(SqlClient.SqlClient, sql)),
+        Layer.orDie,
+      ),
+    };
+  }),
+});
+```
+
+`databaseUrl`, `loader`, `Api`, `handlers` and `sessions` are the application's existing host inputs. The route above receives GitHub deliveries at `POST /webhooks/github`. It uses the existing `appHost.routes` option and the host's `maxBodySize`; the jobs client and SQL client must point at the same PostgreSQL database. Register workers separately with the job definitions' `handle` method, in the processes your application chooses.
+
+### Answers and retries
+
+| Request | Status | Body |
+| --- | --- | --- |
+| Registered event maps to jobs | 202 | `queued` |
+| Unlisted event, or mapping returns no jobs | 200 | `ignored` |
+| Source and delivery ID already recorded | 200 | `already queued` |
+| Unregistered source | 404 | Empty |
+| Missing or wrong signature | 401 | Empty |
+| Missing delivery ID or event header | 400 | `Invalid delivery` |
+| Payload rejected by its Schema | 400 | Empty |
+| Body exceeds the host limit | 413 | Empty |
+| Database or enqueue failure | 503 | Empty |
+
+Refused requests create no receipt and no jobs. Signatures are checked before decoding; unlisted events are verified and recorded without decoding. The signing key, signature and raw body stay out of responses, logs and spans.
+
+The receipt insert and every enqueue use one SQL transaction. Concurrent copies wait on the receipt's unique key: a committed first copy makes the second a duplicate; a rolled-back first copy lets the second receive the delivery itself. If any enqueue fails, earlier enqueues and the receipt roll back, and the sender's retry can succeed. Receipts for ignored events are deduplicated too.
+
+### Other senders
+
+`githubSource` supplies `githubStrategy`, which checks `X-Hub-Signature-256` through `@shivaedev/github` and reads `X-GitHub-Delivery` and `X-GitHub-Event`. Each key is a `Config.Config<Redacted.Redacted<string>>` and is resolved when the route Layer starts.
+
+For another sender, supply a `WebhookSource` from `registration.ts` with its own `WebhookStrategy`. Its `verify(body, headers, key)` returns an Effect that fails with `WebhookUnauthorized` from `WebhookUnauthorized.ts` for invalid signatures. Its `delivery(headers)` returns `{ id, event }`; neither field comes from the payload. The route, receipts and queue mapping stay the same.
+
+Applications install `@shivaedev/platform` and import this package by name. Libraries can install `@shivaedev/webhooks` directly with the Effect, Node HTTP and pg-boss peers used by their host. The stories run against `PLATFORM_JOBS_TEST_DATABASE_URL`, using real HTTP and isolated PostgreSQL databases.

package/dist/WebhookUnauthorized.d.ts

@@ -0,0 +1,7 @@
+declare const WebhookUnauthorized_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "WebhookUnauthorized";
+} & Readonly<A>;
+export declare class WebhookUnauthorized extends WebhookUnauthorized_base {
+}
+export {};
+//# sourceMappingURL=WebhookUnauthorized.d.ts.map

package/dist/WebhookUnauthorized.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebhookUnauthorized.d.ts","sourceRoot":"","sources":["../src/WebhookUnauthorized.ts"],"names":[],"mappings":";;;AAEA,qBAAa,mBAAoB,SAAQ,wBAAuC;CAAG"}

package/dist/WebhookUnauthorized.js

@@ -0,0 +1,4 @@
+import { Data } from "effect";
+export class WebhookUnauthorized extends Data.TaggedError("WebhookUnauthorized") {
+}
+//# sourceMappingURL=WebhookUnauthorized.js.map

package/dist/WebhookUnauthorized.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebhookUnauthorized.js","sourceRoot":"","sources":["../src/WebhookUnauthorized.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AAE9B,MAAM,OAAO,mBAAoB,SAAQ,IAAI,CAAC,WAAW,CAAC,qBAAqB,CAAC;CAAG"}

package/dist/github.d.ts

@@ -0,0 +1,4 @@
+import type { WebhookSource, WebhookStrategy } from "#registration.ts";
+export declare const githubStrategy: WebhookStrategy;
+export declare function githubSource<R>(options: Omit<WebhookSource<R>, "strategy">): WebhookSource<R>;
+//# sourceMappingURL=github.d.ts.map

package/dist/github.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"github.d.ts","sourceRoot":"","sources":["../src/github.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAGvE,eAAO,MAAM,cAAc,EAAE,eAG5B,CAAC;AAEF,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,CAE7F"}

package/dist/github.js

@@ -0,0 +1,11 @@
+import { Effect } from "effect";
+import { verifyWebhook } from "@shivaedev/github/verifyWebhook.ts";
+import { WebhookUnauthorized } from "#WebhookUnauthorized.ts";
+export const githubStrategy = {
+    delivery: (headers) => ({ event: headers["x-github-event"], id: headers["x-github-delivery"] }),
+    verify: (body, headers, key) => verifyWebhook(body, headers["x-hub-signature-256"], key).pipe(Effect.mapError(() => new WebhookUnauthorized())),
+};
+export function githubSource(options) {
+    return { ...options, strategy: githubStrategy };
+}
+//# sourceMappingURL=github.js.map

package/dist/github.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"github.js","sourceRoot":"","sources":["../src/github.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,aAAa,EAAE,MAAM,oCAAoC,CAAC;AAEnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAE9D,MAAM,CAAC,MAAM,cAAc,GAAoB;IAC9C,QAAQ,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,gBAAgB,CAAC,EAAE,EAAE,EAAE,OAAO,CAAC,mBAAmB,CAAC,EAAE,CAAC;IAC/F,MAAM,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,EAAE,CAAC,aAAa,CAAC,IAAI,EAAE,OAAO,CAAC,qBAAqB,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,mBAAmB,EAAE,CAAC,CAAC;CAC/I,CAAC;AAEF,MAAM,UAAU,YAAY,CAAI,OAA2C;IAC1E,OAAO,EAAE,GAAG,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAC;AACjD,CAAC"}

package/dist/internal/receive.d.ts

@@ -0,0 +1,7 @@
+import { Effect, type Redacted } from "effect";
+import { HttpServerResponse } from "effect/http";
+import { SqlClient } from "effect/sql";
+import type { PgBossService } from "@shivaedev/jobs/server/service.ts";
+import { type WebhookSource } from "#registration.ts";
+export declare const receive: <R>(name: string, source: WebhookSource<R>, key: Redacted.Redacted<string>, body: Uint8Array<ArrayBufferLike>, headers: Readonly<Record<string, string>>, jobs: PgBossService) => Effect.Effect<HttpServerResponse.HttpServerResponse, import("@shivaedev/jobs/server/error.ts").PgBossError | import("@shivaedev/jobs/server/error.ts").PgBossPayloadError | import("effect/Schema").SchemaError | import("effect/sql/SqlError").SqlError | import("../WebhookUnauthorized.ts").WebhookUnauthorized, R | SqlClient.SqlClient>;
+//# sourceMappingURL=receive.d.ts.map

package/dist/internal/receive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"receive.d.ts","sourceRoot":"","sources":["../../src/internal/receive.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAU,KAAK,QAAQ,EAAE,MAAM,QAAQ,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AACvE,OAAO,EAAsB,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAE1E,eAAO,MAAM,OAAO,GAAgC,CAAC,4fA6BnD,CAAC"}

package/dist/internal/receive.js

@@ -0,0 +1,26 @@
+import { Effect, Option } from "effect";
+import { HttpServerResponse } from "effect/http";
+import { SqlClient } from "effect/sql";
+import { enqueueWebhookJobs } from "#registration.ts";
+export const receive = Effect.fnUntraced(function* (name, source, key, body, headers, jobs) {
+    yield* source.strategy.verify(body, headers, key);
+    const { id, event } = source.strategy.delivery(headers);
+    if (!(id && event)) {
+        return HttpServerResponse.text("Invalid delivery", { status: 400 });
+    }
+    const definition = Object.hasOwn(source.events, event) ? source.events[event] : undefined;
+    const sql = yield* SqlClient.SqlClient;
+    return yield* sql.withTransaction(Effect.gen(function* () {
+        const inserted = yield* sql `insert into webhook_receipts (source, delivery_id, event, outcome, job_ids)
+				values (${name}, ${id}, ${event}, 'ignored', '[]'::jsonb)
+				on conflict (source, delivery_id) do nothing returning delivery_id`;
+        if (inserted.length === 0) {
+            return HttpServerResponse.text("already queued", { status: 200 });
+        }
+        const requests = definition === undefined ? [] : yield* definition.decode(body);
+        const ids = (yield* enqueueWebhookJobs(requests, jobs)).flatMap(Option.toArray);
+        yield* sql `update webhook_receipts set job_ids = ${JSON.stringify(ids)}::jsonb, outcome = ${requests.length === 0 ? "ignored" : "queued"} where source = ${name} and delivery_id = ${id}`;
+        return HttpServerResponse.text(requests.length === 0 ? "ignored" : "queued", { status: requests.length === 0 ? 200 : 202 });
+    }));
+});
+//# sourceMappingURL=receive.js.map

package/dist/internal/receive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"receive.js","sourceRoot":"","sources":["../../src/internal/receive.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,EAAiB,MAAM,QAAQ,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,OAAO,EAAE,kBAAkB,EAAsB,MAAM,kBAAkB,CAAC;AAE1E,MAAM,CAAC,MAAM,OAAO,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,EACjD,IAAY,EACZ,MAAwB,EACxB,GAA8B,EAC9B,IAAgB,EAChB,OAAyC,EACzC,IAAmB;IAEnB,KAAK,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;IAClD,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACxD,IAAI,CAAC,CAAC,EAAE,IAAI,KAAK,CAAC,EAAE,CAAC;QACpB,OAAO,kBAAkB,CAAC,IAAI,CAAC,kBAAkB,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;IACrE,CAAC;IACD,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC1F,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC;IACvC,OAAO,KAAK,CAAC,CAAC,GAAG,CAAC,eAAe,CAChC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;QACnB,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,GAAG,CAAA;cAChB,IAAI,KAAK,EAAE,KAAK,KAAK;uEACoC,CAAC;QACrE,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3B,OAAO,kBAAkB,CAAC,IAAI,CAAC,gBAAgB,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;QACnE,CAAC;QACD,MAAM,QAAQ,GAAG,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QAChF,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,kBAAkB,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAChF,KAAK,CAAC,CAAC,GAAG,CAAA,yCAAyC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,sBAAsB,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,mBAAmB,IAAI,sBAAsB,EAAE,EAAE,CAAC;QAC1L,OAAO,kBAAkB,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;IAC7H,CAAC,CAAC,CACF,CAAC;AACH,CAAC,CAAC,CAAC"}

package/dist/registration.d.ts

@@ -0,0 +1,29 @@
+import { type Config, Effect, type Option, type Redacted, Schema } from "effect";
+import type { JobPayloadSchema, QueueDefinition } from "@shivaedev/jobs/server/definition.ts";
+import type { PgBossError, PgBossPayloadError } from "@shivaedev/jobs/server/error.ts";
+import type { PgBossService } from "@shivaedev/jobs/server/service.ts";
+import type { WebhookUnauthorized } from "#WebhookUnauthorized.ts";
+declare const enqueue: unique symbol;
+export interface WebhookJob<R = never> {
+    readonly [enqueue]: (jobs: PgBossService) => Effect.Effect<Option.Option<string>, PgBossError | PgBossPayloadError, R>;
+}
+export declare function webhookJob<const TName extends string, TPayload extends JobPayloadSchema>(queue: QueueDefinition<TName, TPayload>, payload: NoInfer<Schema.Schema.Type<TPayload>>): WebhookJob<TPayload["EncodingServices"]>;
+export interface WebhookEvent<R = never> {
+    readonly decode: (body: Uint8Array) => Effect.Effect<readonly WebhookJob<R>[], Schema.SchemaError, R>;
+}
+export declare function webhookEvent<TSchema extends Schema.Constraint, R = never>(schema: TSchema, jobs: (payload: TSchema["Type"]) => readonly WebhookJob<R>[]): WebhookEvent<TSchema["DecodingServices"] | R>;
+export interface WebhookSource<R = never> {
+    readonly events: Readonly<Record<string, WebhookEvent<R>>>;
+    readonly key: Config.Config<Redacted.Redacted<string>>;
+    readonly strategy: WebhookStrategy;
+}
+export interface WebhookStrategy {
+    readonly delivery: (headers: Readonly<Record<string, string>>) => {
+        readonly id: string | undefined;
+        readonly event: string | undefined;
+    };
+    readonly verify: (body: Uint8Array, headers: Readonly<Record<string, string>>, key: Redacted.Redacted<string>) => Effect.Effect<void, WebhookUnauthorized>;
+}
+export declare function enqueueWebhookJobs<R>(requests: readonly WebhookJob<R>[], jobs: PgBossService): Effect.Effect<Option.Option<string>[], PgBossError | PgBossPayloadError, R>;
+export {};
+//# sourceMappingURL=registration.d.ts.map

package/dist/registration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registration.d.ts","sourceRoot":"","sources":["../src/registration.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,EAAE,KAAK,MAAM,EAAE,KAAK,QAAQ,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACjF,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,sCAAsC,CAAC;AAC9F,OAAO,KAAK,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AACvF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AACvE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAEnE,QAAA,MAAM,OAAO,eAA+B,CAAC;AAE7C,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,KAAK;IACpC,QAAQ,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,kBAAkB,EAAE,CAAC,CAAC,CAAC;CACvH;AAED,wBAAgB,UAAU,CAAC,KAAK,CAAC,KAAK,SAAS,MAAM,EAAE,QAAQ,SAAS,gBAAgB,EACvF,KAAK,EAAE,eAAe,CAAC,KAAK,EAAE,QAAQ,CAAC,EACvC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,GAC5C,UAAU,CAAC,QAAQ,CAAC,kBAAkB,CAAC,CAAC,CAE1C;AAED,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,KAAK;IACtC,QAAQ,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,UAAU,KAAK,MAAM,CAAC,MAAM,CAAC,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,EAAE,MAAM,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;CACtG;AAED,wBAAgB,YAAY,CAAC,OAAO,SAAS,MAAM,CAAC,UAAU,EAAE,CAAC,GAAG,KAAK,EACxE,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,KAAK,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,GAC1D,YAAY,CAAC,OAAO,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAC,CAI/C;AAED,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,KAAK;IACvC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;IACvD,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;CACnC;AAED,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,KAAK;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,CAAC;IAC1I,QAAQ,CAAC,MAAM,EAAE,CAChB,IAAI,EAAE,UAAU,EAChB,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EACzC,GAAG,EAAE,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,KAC1B,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,mBAAmB,CAAC,CAAC;CAC9C;AAED,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,QAAQ,EAAE,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,aAAa,+EAE5F"}

package/dist/registration.js

@@ -0,0 +1,14 @@
+import { Effect, Schema } from "effect";
+const enqueue = Symbol("WebhookJob.enqueue");
+export function webhookJob(queue, payload) {
+    return { [enqueue]: (jobs) => jobs.enqueue(queue, payload) };
+}
+export function webhookEvent(schema, jobs) {
+    return {
+        decode: (body) => Schema.decodeUnknownEffect(Schema.fromJsonString(schema))(new TextDecoder().decode(body)).pipe(Effect.map(jobs)),
+    };
+}
+export function enqueueWebhookJobs(requests, jobs) {
+    return Effect.forEach(requests, (request) => request[enqueue](jobs));
+}
+//# sourceMappingURL=registration.js.map

package/dist/registration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registration.js","sourceRoot":"","sources":["../src/registration.ts"],"names":[],"mappings":"AAAA,OAAO,EAAe,MAAM,EAA8B,MAAM,EAAE,MAAM,QAAQ,CAAC;AAMjF,MAAM,OAAO,GAAG,MAAM,CAAC,oBAAoB,CAAC,CAAC;AAM7C,MAAM,UAAU,UAAU,CACzB,KAAuC,EACvC,OAA8C;IAE9C,OAAO,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,CAAC;AAC9D,CAAC;AAMD,MAAM,UAAU,YAAY,CAC3B,MAAe,EACf,IAA4D;IAE5D,OAAO;QACN,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,MAAM,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;KAClI,CAAC;AACH,CAAC;AAiBD,MAAM,UAAU,kBAAkB,CAAI,QAAkC,EAAE,IAAmB;IAC5F,OAAO,MAAM,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AACtE,CAAC"}

package/dist/route.d.ts

@@ -0,0 +1,12 @@
+import { type Context, Layer } from "effect";
+import { HttpRouter } from "effect/http";
+import type { SqlClient } from "effect/sql";
+import type { PgBossService } from "@shivaedev/jobs/server/service.ts";
+import type { WebhookSource } from "#registration.ts";
+export interface WebhookRouteOptions<TJobs, R> {
+    readonly basePath: `/${string}`;
+    readonly jobs: Context.Key<TJobs, PgBossService>;
+    readonly sources: Readonly<Record<string, WebhookSource<R>>>;
+}
+export declare function webhookRoute<TJobs, R>(options: WebhookRouteOptions<TJobs, R>): Layer.Layer<never, never, HttpRouter.HttpRouter | SqlClient.SqlClient | Exclude<R, import("effect/Scope").Scope> | Exclude<TJobs, import("effect/Scope").Scope>>;
+//# sourceMappingURL=route.d.ts.map

package/dist/route.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../src/route.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAU,KAAK,EAAiB,MAAM,QAAQ,CAAC;AACpE,OAAO,EAAE,UAAU,EAAsB,MAAM,aAAa,CAAC;AAC7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAEvE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,MAAM,WAAW,mBAAmB,CAAC,KAAK,EAAE,CAAC;IAC5C,QAAQ,CAAC,QAAQ,EAAE,IAAI,MAAM,EAAE,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC;IACjD,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC7D;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,mBAAmB,CAAC,KAAK,EAAE,CAAC,CAAC,oKA6B5E"}

package/dist/route.js

@@ -0,0 +1,26 @@
+import { Effect, Layer } from "effect";
+import { HttpRouter, HttpServerResponse } from "effect/http";
+import { readBoundedBody } from "@shivaedev/http/server/boundedBody.ts";
+import { receive } from "#internal/receive.ts";
+export function webhookRoute(options) {
+    return Layer.unwrap(Effect.gen(function* () {
+        const context = yield* Effect.context();
+        const jobs = yield* options.jobs;
+        const keys = new Map();
+        for (const [name, source] of Object.entries(options.sources)) {
+            keys.set(name, yield* source.key);
+        }
+        return HttpRouter.add("POST", `/${options.basePath.replace(/^\/|\/$/gu, "")}/:source`, (request) => Effect.gen(function* () {
+            const { params } = yield* HttpRouter.RouteContext;
+            const name = params.source ?? "";
+            const source = Object.hasOwn(options.sources, name) ? options.sources[name] : undefined;
+            const key = keys.get(name);
+            if (source === undefined || key === undefined) {
+                return HttpServerResponse.empty({ status: 404 });
+            }
+            const body = new Uint8Array(yield* readBoundedBody(request));
+            return yield* receive(name, source, key, body, request.headers, jobs).pipe(Effect.provideContext(context));
+        }).pipe(Effect.catchTag("RequestBodyTooLarge", () => Effect.succeed(HttpServerResponse.empty({ status: 413 }))), Effect.catchTag("WebhookUnauthorized", () => Effect.succeed(HttpServerResponse.empty({ status: 401 }))), Effect.catchTag("SchemaError", () => Effect.succeed(HttpServerResponse.empty({ status: 400 }))), Effect.catch(() => Effect.succeed(HttpServerResponse.empty({ status: 503 })))));
+    }).pipe(Effect.orDie));
+}
+//# sourceMappingURL=route.js.map

package/dist/route.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.js","sourceRoot":"","sources":["../src/route.ts"],"names":[],"mappings":"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"}

package/dist/webhookReceipts.d.ts

@@ -0,0 +1,3 @@
+import type { SchemaComponent } from "@shivaedev/sql/SchemaComponent.ts";
+export declare const webhookReceipts: SchemaComponent;
+//# sourceMappingURL=webhookReceipts.d.ts.map

package/dist/webhookReceipts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhookReceipts.d.ts","sourceRoot":"","sources":["../src/webhookReceipts.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAEzE,eAAO,MAAM,eAAe,EAAE,eAmB7B,CAAC"}

package/dist/webhookReceipts.js

@@ -0,0 +1,23 @@
+import { Effect } from "effect";
+import { SqlClient } from "effect/sql";
+export const webhookReceipts = {
+    apply: Effect.gen(function* () {
+        const sql = yield* SqlClient.SqlClient;
+        yield* sql `create table if not exists webhook_receipts (
+			source text not null,
+			delivery_id text not null,
+			event text not null,
+			received_at timestamptz not null default now(),
+			outcome text not null check (outcome in ('queued', 'ignored')),
+			job_ids jsonb not null,
+			primary key (source, delivery_id)
+		)`;
+    }),
+    name: "webhook-receipts",
+    pending: Effect.gen(function* () {
+        const sql = yield* SqlClient.SqlClient;
+        const [row] = yield* sql `select to_regclass('webhook_receipts')::text as name`;
+        return row === undefined || row.name === null ? "webhook_receipts is missing" : undefined;
+    }),
+};
+//# sourceMappingURL=webhookReceipts.js.map

package/dist/webhookReceipts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhookReceipts.js","sourceRoot":"","sources":["../src/webhookReceipts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGvC,MAAM,CAAC,MAAM,eAAe,GAAoB;IAC/C,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;QAC1B,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC;QACvC,KAAK,CAAC,CAAC,GAAG,CAAA;;;;;;;;IAQR,CAAC;IACJ,CAAC,CAAC;IACF,IAAI,EAAE,kBAAkB;IACxB,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;QAC5B,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC;QACvC,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG,CAAyB,sDAAsD,CAAC;QACxG,OAAO,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,6BAA6B,CAAC,CAAC,CAAC,SAAS,CAAC;IAC3F,CAAC,CAAC;CACF,CAAC"}

package/package.json

@@ -1,6 +1,87 @@
 {
   "name": "@shivaedev/webhooks",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Verified webhook receipts and transactional job delivery over Effect HTTP",
+  "keywords": [
+    "effect"
+  ],
+  "homepage": "https://github.com/ShivaeDev/platform/tree/main/packages/webhooks#readme",
+  "bugs": {
+    "url": "https://github.com/ShivaeDev/platform/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShivaeDev/platform.git",
+    "directory": "packages/webhooks"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "imports": {
+    "#test/*": "./src/test-support/*",
+    "#*.ts": {
+      "source": "./src/*.ts",
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
+  },
+  "exports": {
+    "./*.ts": {
+      "source": "./src/*.ts",
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    },
+    "./package.json": "./package.json",
+    "./internal/*": null
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.spec.ts",
+    "!src/**/*.spec.tsx",
+    "!src/**/test-support",
+    "README.md"
+  ],
+  "dependencies": {
+    "@shivaedev/github": "0.7.0",
+    "@shivaedev/http": "0.1.0",
+    "@shivaedev/jobs": "0.21.0",
+    "@shivaedev/sql": "0.23.0"
+  },
+  "devDependencies": {
+    "@effect/platform-node": "4.0.5",
+    "@shivaedev/quality": "0.42.0",
+    "@shivaedev/server": "0.2.0",
+    "@shivaedev/test-sql": "0.10.1",
+    "@shivaedev/test-story": "0.21.1",
+    "@types/node": "24.19.2",
+    "effect": "4.0.5",
+    "pg-boss": "12.38.0",
+    "typescript": "7.0.2",
+    "vitest": "5.0.5"
+  },
+  "peerDependencies": {
+    "@effect/platform-node": "4.0.5",
+    "effect": "4.0.5"
+  },
+  "peerDependenciesMeta": {
+    "@effect/platform-node": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "node --eval \"import('node:fs').then(({ rmSync }) => rmSync('dist', { force: true, recursive: true }))\" && tsc --project tsconfig.build.json",
+    "ready": "pnpm typecheck && pnpm test && pnpm build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
 }

package/src/WebhookUnauthorized.ts

@@ -0,0 +1,3 @@
+import { Data } from "effect";
+
+export class WebhookUnauthorized extends Data.TaggedError("WebhookUnauthorized") {}

package/src/github.ts

@@ -0,0 +1,13 @@
+import { Effect } from "effect";
+import { verifyWebhook } from "@shivaedev/github/verifyWebhook.ts";
+import type { WebhookSource, WebhookStrategy } from "#registration.ts";
+import { WebhookUnauthorized } from "#WebhookUnauthorized.ts";
+
+export const githubStrategy: WebhookStrategy = {
+	delivery: (headers) => ({ event: headers["x-github-event"], id: headers["x-github-delivery"] }),
+	verify: (body, headers, key) => verifyWebhook(body, headers["x-hub-signature-256"], key).pipe(Effect.mapError(() => new WebhookUnauthorized())),
+};
+
+export function githubSource<R>(options: Omit<WebhookSource<R>, "strategy">): WebhookSource<R> {
+	return { ...options, strategy: githubStrategy };
+}

package/src/internal/receive.ts

@@ -0,0 +1,36 @@
+import { Effect, Option, type Redacted } from "effect";
+import { HttpServerResponse } from "effect/http";
+import { SqlClient } from "effect/sql";
+import type { PgBossService } from "@shivaedev/jobs/server/service.ts";
+import { enqueueWebhookJobs, type WebhookSource } from "#registration.ts";
+
+export const receive = Effect.fnUntraced(function* <R>(
+	name: string,
+	source: WebhookSource<R>,
+	key: Redacted.Redacted<string>,
+	body: Uint8Array,
+	headers: Readonly<Record<string, string>>,
+	jobs: PgBossService,
+) {
+	yield* source.strategy.verify(body, headers, key);
+	const { id, event } = source.strategy.delivery(headers);
+	if (!(id && event)) {
+		return HttpServerResponse.text("Invalid delivery", { status: 400 });
+	}
+	const definition = Object.hasOwn(source.events, event) ? source.events[event] : undefined;
+	const sql = yield* SqlClient.SqlClient;
+	return yield* sql.withTransaction(
+		Effect.gen(function* () {
+			const inserted = yield* sql`insert into webhook_receipts (source, delivery_id, event, outcome, job_ids)
+				values (${name}, ${id}, ${event}, 'ignored', '[]'::jsonb)
+				on conflict (source, delivery_id) do nothing returning delivery_id`;
+			if (inserted.length === 0) {
+				return HttpServerResponse.text("already queued", { status: 200 });
+			}
+			const requests = definition === undefined ? [] : yield* definition.decode(body);
+			const ids = (yield* enqueueWebhookJobs(requests, jobs)).flatMap(Option.toArray);
+			yield* sql`update webhook_receipts set job_ids = ${JSON.stringify(ids)}::jsonb, outcome = ${requests.length === 0 ? "ignored" : "queued"} where source = ${name} and delivery_id = ${id}`;
+			return HttpServerResponse.text(requests.length === 0 ? "ignored" : "queued", { status: requests.length === 0 ? 200 : 202 });
+		}),
+	);
+});

package/src/registration.ts

@@ -0,0 +1,50 @@
+import { type Config, Effect, type Option, type Redacted, Schema } from "effect";
+import type { JobPayloadSchema, QueueDefinition } from "@shivaedev/jobs/server/definition.ts";
+import type { PgBossError, PgBossPayloadError } from "@shivaedev/jobs/server/error.ts";
+import type { PgBossService } from "@shivaedev/jobs/server/service.ts";
+import type { WebhookUnauthorized } from "#WebhookUnauthorized.ts";
+
+const enqueue = Symbol("WebhookJob.enqueue");
+
+export interface WebhookJob<R = never> {
+	readonly [enqueue]: (jobs: PgBossService) => Effect.Effect<Option.Option<string>, PgBossError | PgBossPayloadError, R>;
+}
+
+export function webhookJob<const TName extends string, TPayload extends JobPayloadSchema>(
+	queue: QueueDefinition<TName, TPayload>,
+	payload: NoInfer<Schema.Schema.Type<TPayload>>,
+): WebhookJob<TPayload["EncodingServices"]> {
+	return { [enqueue]: (jobs) => jobs.enqueue(queue, payload) };
+}
+
+export interface WebhookEvent<R = never> {
+	readonly decode: (body: Uint8Array) => Effect.Effect<readonly WebhookJob<R>[], Schema.SchemaError, R>;
+}
+
+export function webhookEvent<TSchema extends Schema.Constraint, R = never>(
+	schema: TSchema,
+	jobs: (payload: TSchema["Type"]) => readonly WebhookJob<R>[],
+): WebhookEvent<TSchema["DecodingServices"] | R> {
+	return {
+		decode: (body) => Schema.decodeUnknownEffect(Schema.fromJsonString(schema))(new TextDecoder().decode(body)).pipe(Effect.map(jobs)),
+	};
+}
+
+export interface WebhookSource<R = never> {
+	readonly events: Readonly<Record<string, WebhookEvent<R>>>;
+	readonly key: Config.Config<Redacted.Redacted<string>>;
+	readonly strategy: WebhookStrategy;
+}
+
+export interface WebhookStrategy {
+	readonly delivery: (headers: Readonly<Record<string, string>>) => { readonly id: string | undefined; readonly event: string | undefined };
+	readonly verify: (
+		body: Uint8Array,
+		headers: Readonly<Record<string, string>>,
+		key: Redacted.Redacted<string>,
+	) => Effect.Effect<void, WebhookUnauthorized>;
+}
+
+export function enqueueWebhookJobs<R>(requests: readonly WebhookJob<R>[], jobs: PgBossService) {
+	return Effect.forEach(requests, (request) => request[enqueue](jobs));
+}

package/src/route.ts

@@ -0,0 +1,44 @@
+import { type Context, Effect, Layer, type Redacted } from "effect";
+import { HttpRouter, HttpServerResponse } from "effect/http";
+import type { SqlClient } from "effect/sql";
+import { readBoundedBody } from "@shivaedev/http/server/boundedBody.ts";
+import type { PgBossService } from "@shivaedev/jobs/server/service.ts";
+import { receive } from "#internal/receive.ts";
+import type { WebhookSource } from "#registration.ts";
+
+export interface WebhookRouteOptions<TJobs, R> {
+	readonly basePath: `/${string}`;
+	readonly jobs: Context.Key<TJobs, PgBossService>;
+	readonly sources: Readonly<Record<string, WebhookSource<R>>>;
+}
+
+export function webhookRoute<TJobs, R>(options: WebhookRouteOptions<TJobs, R>) {
+	return Layer.unwrap(
+		Effect.gen(function* () {
+			const context = yield* Effect.context<TJobs | R | SqlClient.SqlClient>();
+			const jobs = yield* options.jobs;
+			const keys = new Map<string, Redacted.Redacted<string>>();
+			for (const [name, source] of Object.entries(options.sources)) {
+				keys.set(name, yield* source.key);
+			}
+			return HttpRouter.add("POST", `/${options.basePath.replace(/^\/|\/$/gu, "")}/:source`, (request) =>
+				Effect.gen(function* () {
+					const { params } = yield* HttpRouter.RouteContext;
+					const name = params.source ?? "";
+					const source = Object.hasOwn(options.sources, name) ? options.sources[name] : undefined;
+					const key = keys.get(name);
+					if (source === undefined || key === undefined) {
+						return HttpServerResponse.empty({ status: 404 });
+					}
+					const body = new Uint8Array(yield* readBoundedBody(request));
+					return yield* receive(name, source, key, body, request.headers, jobs).pipe(Effect.provideContext(context));
+				}).pipe(
+					Effect.catchTag("RequestBodyTooLarge", () => Effect.succeed(HttpServerResponse.empty({ status: 413 }))),
+					Effect.catchTag("WebhookUnauthorized", () => Effect.succeed(HttpServerResponse.empty({ status: 401 }))),
+					Effect.catchTag("SchemaError", () => Effect.succeed(HttpServerResponse.empty({ status: 400 }))),
+					Effect.catch(() => Effect.succeed(HttpServerResponse.empty({ status: 503 }))),
+				),
+			);
+		}).pipe(Effect.orDie),
+	);
+}

package/src/webhookReceipts.ts

@@ -0,0 +1,24 @@
+import { Effect } from "effect";
+import { SqlClient } from "effect/sql";
+import type { SchemaComponent } from "@shivaedev/sql/SchemaComponent.ts";
+
+export const webhookReceipts: SchemaComponent = {
+	apply: Effect.gen(function* () {
+		const sql = yield* SqlClient.SqlClient;
+		yield* sql`create table if not exists webhook_receipts (
+			source text not null,
+			delivery_id text not null,
+			event text not null,
+			received_at timestamptz not null default now(),
+			outcome text not null check (outcome in ('queued', 'ignored')),
+			job_ids jsonb not null,
+			primary key (source, delivery_id)
+		)`;
+	}),
+	name: "webhook-receipts",
+	pending: Effect.gen(function* () {
+		const sql = yield* SqlClient.SqlClient;
+		const [row] = yield* sql<{ name: string | null }>`select to_regclass('webhook_receipts')::text as name`;
+		return row === undefined || row.name === null ? "webhook_receipts is missing" : undefined;
+	}),
+};