tapimo 0.0.0 → 0.0.2

package/src/apps/webhooks.test.ts

@@ -0,0 +1,1937 @@
+import { Store, Webhooks as Core } from 'cadent'
+
+import * as Tidx from '../internal/Tidx.js'
+import * as Viem from '../internal/Viem.js'
+import * as TestApp from '../../test/App.js'
+import * as Mppx from '../../test/Mppx.js'
+import * as Runtime from '../../test/runtime.js'
+import * as Tempo from '../../test/Tempo.js'
+import * as Webhooks from './webhooks.js'
+
+/** API key with both webhook scopes, owned by `org_test`. */
+const writer = {
+  id: 'key_writer',
+  orgId: 'org_test',
+  scopes: ['webhooks:read', 'webhooks:write'],
+  token: 'secret_writer',
+} satisfies TestApp.source.Key
+
+/** API key with read-only webhook scope, owned by `org_test`. */
+const reader = {
+  id: 'key_reader',
+  orgId: 'org_test',
+  scopes: ['webhooks:read'],
+  token: 'secret_reader',
+} satisfies TestApp.source.Key
+
+/** API key in a different org, used to prove owner isolation. */
+const other = {
+  id: 'key_other',
+  orgId: 'org_other',
+  scopes: ['webhooks:read', 'webhooks:write'],
+  token: 'secret_other',
+} satisfies TestApp.source.Key
+
+/** Creates a webhooks-enabled test client backed by an in-memory state store. */
+function client(keys: readonly TestApp.source.Key[] = [writer, reader, other]) {
+  return TestApp.client({
+    auth: { source: TestApp.source({ keys }) },
+    webhook: { store: Store.memory() },
+  })
+}
+
+/** RequestInit carrying a bearer token for the given key. */
+function as(key: { token: string }) {
+  return { headers: { authorization: `Bearer ${key.token}` } } as const
+}
+
+/** Minimal valid creation payload. */
+const validBody = {
+  destination: { type: 'url', url: 'https://example.com/hook' },
+  eventType: 'token:transfer',
+} as const
+
+describe('feature gate', () => {
+  test('returns 404 when no state store is configured', async () => {
+    // Routes stay mounted for a stable schema, but the resource is disabled.
+    // `event-types` requires `data:read`, so seed a key that holds it to reach
+    // the feature gate rather than tripping the scope check first.
+    const dataReader = {
+      id: 'key_data_reader',
+      orgId: 'org_test',
+      scopes: ['data:read'],
+      token: 'secret_data_reader',
+    } satisfies TestApp.source.Key
+    const disabled = TestApp.client({ auth: { source: TestApp.source({ keys: [dataReader] }) } })
+    const response = await disabled.v1.webhooks['event-types'].$get({}, as(dataReader))
+
+    expect(response.status).toMatchInlineSnapshot(`404`)
+    const body = (await response.json()) as { error?: { code?: string } }
+    expect(body.error?.code).toMatchInlineSnapshot(`"webhooks_not_enabled"`)
+  })
+})
+
+describe('access matrix', () => {
+  test('rejects anonymous reads with 401 even when MPP is enabled (API-key-only)', async () => {
+    // Webhooks opt out of the paid (MPP) lane for now, so an anonymous caller on
+    // a `public: false` route (`GET /webhooks`) is rejected outright rather than
+    // offered the paid path — even though MPP is enabled app-wide by default.
+    const response = await client().v1.webhooks.$get({ query: {} })
+
+    expect(response.status).toMatchInlineSnapshot(`401`)
+    expect(response.headers.has('www-authenticate')).toMatchInlineSnapshot(`false`)
+  })
+
+  test('rejects an invalid key', async () => {
+    const response = await client().v1.webhooks.$get(
+      { query: {} },
+      { headers: { authorization: 'Bearer nope' } },
+    )
+
+    expect(response.status).toMatchInlineSnapshot(`401`)
+  })
+
+  test('rejects a key missing the read scope', async () => {
+    const noScope = {
+      id: 'key_noscope',
+      orgId: 'org_test',
+      scopes: ['data:read'],
+      token: 'secret_noscope',
+    } satisfies TestApp.source.Key
+    const response = await client([noScope]).v1.webhooks.$get({ query: {} }, as(noScope))
+    const body = (await response.json()) as { error?: { code?: string } }
+
+    expect(response.status).toMatchInlineSnapshot(`403`)
+    expect(body.error?.code).toMatchInlineSnapshot(`"api_key_forbidden"`)
+  })
+
+  test('rejects a read-only key on writes', async () => {
+    const response = await client().v1.webhooks.$post({ json: validBody }, as(reader))
+    const body = (await response.json()) as { error?: { code?: string } }
+
+    expect(response.status).toMatchInlineSnapshot(`403`)
+    expect(body.error?.code).toMatchInlineSnapshot(`"api_key_forbidden"`)
+  })
+
+  test('lists event types without authentication (public catalog)', async () => {
+    // `GET /webhooks/event-types` is intentionally public: anonymous callers are
+    // served within the public quota, no key or scope required.
+    const response = await client().v1.webhooks['event-types'].$get({})
+    const body = await TestApp.json(response, Webhooks.schema.getWebhookEventTypes.Response)
+
+    expect(response.status).toMatchInlineSnapshot(`200`)
+    // The catalog is static public data and must be cacheable (`stable`),
+    // overriding the resource-wide `no-store` default for subscriptions —
+    // without it every request pays the full auth/rate-limit floor.
+    expect(response.headers.get('cache-control')).toMatchInlineSnapshot(
+      `"private, max-age=300, stale-while-revalidate=3600"`,
+    )
+    expect(body.data.map((entry) => entry.type)).toMatchInlineSnapshot(`
+      [
+        "block:created",
+        "log:emitted",
+        "token:transfer",
+        "transaction:included",
+      ]
+    `)
+  })
+
+  test('lists event types for a key with the data:read scope', async () => {
+    const dataReader = {
+      id: 'key_data_reader',
+      orgId: 'org_test',
+      scopes: ['data:read'],
+      token: 'secret_data_reader',
+    } satisfies TestApp.source.Key
+    const response = await client([dataReader]).v1.webhooks['event-types'].$get({}, as(dataReader))
+
+    expect(response.status).toMatchInlineSnapshot(`200`)
+  })
+
+  test('rejects a key lacking the data:read scope', async () => {
+    const response = await client().v1.webhooks['event-types'].$get({}, as(reader))
+    const body = (await response.json()) as { error?: { code?: string } }
+
+    expect(response.status).toMatchInlineSnapshot(`403`)
+    expect(body.error?.code).toMatchInlineSnapshot(`"api_key_forbidden"`)
+  })
+})
+
+describe('CRUD lifecycle', () => {
+  test('creates, reads, lists, updates, and deletes a subscription', async () => {
+    const app = client()
+
+    // Create returns the one-time signing secret.
+    const created = await app.v1.webhooks.$post({ json: validBody }, as(writer))
+    const createdBody = await TestApp.json(created, Webhooks.schema.createWebhook.Response)
+    expect(created.status).toMatchInlineSnapshot(`200`)
+    expect(createdBody.id.startsWith('wh_')).toBe(true)
+    expect(createdBody.secret.startsWith('whsec_')).toBe(true)
+    expect(createdBody.status).toMatchInlineSnapshot(`"active"`)
+    expect(createdBody.destination.url).toMatchInlineSnapshot(`"https://example.com/hook"`)
+    // API-key-owned subscriptions never expire.
+    expect(createdBody.expiresAt).toMatchInlineSnapshot(`undefined`)
+    expect(createdBody).not.toHaveProperty('owner')
+
+    // Reads never expose the secret.
+    const read = await app.v1.webhooks[':id{wh_[A-Za-z0-9_-]+}'].$get(
+      { param: { id: createdBody.id } },
+      as(writer),
+    )
+    const readBody = await TestApp.json(read, Webhooks.schema.getWebhook.Response)
+    expect(read.status).toMatchInlineSnapshot(`200`)
+    expect(readBody.id).toBe(createdBody.id)
+    expect(readBody).not.toHaveProperty('secret')
+    expect(read.headers.get('cache-control')).toMatchInlineSnapshot(`"no-store"`)
+
+    // List shows the subscription.
+    const listed = await app.v1.webhooks.$get({ query: {} }, as(writer))
+    const listedBody = await TestApp.json(listed, Webhooks.schema.listWebhooks.Response)
+    expect(listed.status).toMatchInlineSnapshot(`200`)
+    expect(listedBody.data.map((entry) => entry.id)).toContain(createdBody.id)
+
+    // Patch pauses it.
+    const patched = await app.v1.webhooks[':id{wh_[A-Za-z0-9_-]+}'].$patch(
+      { json: { status: 'paused' }, param: { id: createdBody.id } },
+      as(writer),
+    )
+    const patchedBody = await TestApp.json(patched, Webhooks.schema.updateWebhook.Response)
+    expect(patched.status).toMatchInlineSnapshot(`200`)
+    expect(patchedBody.status).toMatchInlineSnapshot(`"paused"`)
+
+    // Delete removes it, after which reads 404.
+    const deleted = await app.v1.webhooks[':id{wh_[A-Za-z0-9_-]+}'].$delete(
+      { param: { id: createdBody.id } },
+      as(writer),
+    )
+    const deletedBody = await TestApp.json(deleted, Webhooks.schema.deleteWebhook.Response)
+    expect(deleted.status).toMatchInlineSnapshot(`200`)
+    expect(deletedBody.id).toBe(createdBody.id)
+
+    const missing = await app.v1.webhooks[':id{wh_[A-Za-z0-9_-]+}'].$get(
+      { param: { id: createdBody.id } },
+      as(writer),
+    )
+    expect(missing.status).toMatchInlineSnapshot(`404`)
+  })
+
+  test('embeds the exact subscription total via include=totalCount', async () => {
+    const app = client()
+    // Two subscriptions under the writer's owner.
+    await app.v1.webhooks.$post({ json: validBody }, as(writer))
+    await app.v1.webhooks.$post({ json: validBody }, as(writer))
+
+    const listed = await app.v1.webhooks.$get(
+      { query: { include: 'totalCount', limit: '5' } },
+      as(writer),
+    )
+    const body = await TestApp.json(listed, Webhooks.schema.listWebhooks.Response)
+    expect(listed.status).toBe(200)
+    // The count is the owner total, exact.
+    expect(body.data.length).toBe(2)
+    expect(body.meta).toEqual({ totalCountCapped: false, totalCount: 2 })
+
+    // Without the include, `meta` is omitted.
+    const bare = await app.v1.webhooks.$get({ query: { limit: '5' } }, as(writer))
+    const bareBody = await TestApp.json(bare, Webhooks.schema.listWebhooks.Response)
+    expect(bareBody.meta).toBeUndefined()
+  })
+
+  test('a sibling key in the same org manages the org subscription', async () => {
+    const app = client()
+    const created = await app.v1.webhooks.$post({ json: validBody }, as(writer))
+    const { id } = await TestApp.json(created, Webhooks.schema.createWebhook.Response)
+
+    // `reader` shares `org_test`, so it can read but not mutate (scope-gated).
+    const read = await app.v1.webhooks[':id{wh_[A-Za-z0-9_-]+}'].$get({ param: { id } }, as(reader))
+    expect(read.status).toMatchInlineSnapshot(`200`)
+  })
+})
+
+describe('owner isolation', () => {
+  test('a different org cannot see or mutate another org subscription', async () => {
+    const app = client()
+    const created = await app.v1.webhooks.$post({ json: validBody }, as(writer))
+    const { id } = await TestApp.json(created, Webhooks.schema.createWebhook.Response)
+
+    const read = await app.v1.webhooks[':id{wh_[A-Za-z0-9_-]+}'].$get({ param: { id } }, as(other))
+    expect(read.status).toMatchInlineSnapshot(`404`)
+
+    const removed = await app.v1.webhooks[':id{wh_[A-Za-z0-9_-]+}'].$delete(
+      { param: { id } },
+      as(other),
+    )
+    expect(removed.status).toMatchInlineSnapshot(`404`)
+
+    const listed = await app.v1.webhooks.$get({ query: {} }, as(other))
+    const listedBody = await TestApp.json(listed, Webhooks.schema.listWebhooks.Response)
+    expect(listedBody.data).toMatchInlineSnapshot(`[]`)
+  })
+})
+
+describe('subscription limits', () => {
+  test('rejects creation past the configured per-owner cap with 403 limit_exceeded', async () => {
+    const app = TestApp.client({
+      auth: { source: TestApp.source({ keys: [writer, other] }) },
+      webhook: { maxPerOwner: 2, store: Store.memory() },
+    })
+
+    // Fill the writer's quota.
+    for (let i = 0; i < 2; i++) {
+      const ok = await app.v1.webhooks.$post({ json: validBody }, as(writer))
+      expect(ok.status).toMatchInlineSnapshot(`200`)
+    }
+
+    // The third create is over the cap.
+    const over = await app.v1.webhooks.$post({ json: validBody }, as(writer))
+    expect(over.status).toMatchInlineSnapshot(`403`)
+    const body = (await over.json()) as { error?: { code?: string } }
+    expect(body.error?.code).toMatchInlineSnapshot(`"limit_exceeded"`)
+
+    // The cap is per-owner: a different org is unaffected.
+    const otherOrg = await app.v1.webhooks.$post({ json: validBody }, as(other))
+    expect(otherOrg.status).toMatchInlineSnapshot(`200`)
+  })
+})
+
+describe('delivery log', () => {
+  /** A delivery row with a lexically-sortable id, mirroring the core test helper. */
+  function row(subscriptionId: string, n: number): Core.Delivery {
+    return {
+      attempt: n,
+      createdAt: new Date(1_700_000_000_000 + n * 1_000).toISOString(),
+      envelope: {
+        chainId: 4217,
+        createdAt: new Date(1_700_000_000_000 + n * 1_000).toISOString(),
+        data: { amount: String(n) },
+        id: `evt_${n}`,
+        subscriptionId,
+        type: 'token:transfer',
+      },
+      eventId: `evt_${n}`,
+      id: `whd_${String(1_700_000_000_000 + n * 1_000).padStart(15, '0')}_${'0'.repeat(16)}`,
+      requestUrl: 'https://example.com/hook',
+      status: 'succeeded',
+      subscriptionId,
+    }
+  }
+
+  /** Seeds a subscription owned by `writer` plus `count` delivery rows. */
+  async function seed(store: ReturnType<typeof Store.memory>, count: number) {
+    const app = TestApp.client({
+      auth: { source: TestApp.source({ keys: [writer, reader, other] }) },
+      webhook: { store },
+    })
+    const created = await app.v1.webhooks.$post({ json: validBody }, as(writer))
+    const { id } = await TestApp.json(created, Webhooks.schema.createWebhook.Response)
+    for (let n = 1; n <= count; n++) await Core.recordDelivery(store, row(id, n))
+    return { app, id }
+  }
+
+  test('lists a subscription deliveries newest-first', async () => {
+    const store = Store.memory()
+    const { app, id } = await seed(store, 3)
+
+    const response = await app.v1.webhooks[':id{wh_[A-Za-z0-9_-]+}'].deliveries.$get(
+      { param: { id }, query: {} },
+      as(writer),
+    )
+    expect(response.status).toMatchInlineSnapshot(`200`)
+    const body = await TestApp.json(response, Webhooks.schema.listWebhookDeliveries.Response)
+    expect(body.data.map((d) => d.eventId)).toMatchInlineSnapshot(`
+      [
+        "evt_3",
+        "evt_2",
+        "evt_1",
+      ]
+    `)
+    expect(body.nextCursor).toMatchInlineSnapshot(`null`)
+  })
+
+  test('embeds the exact delivery total via include=totalCount', async () => {
+    const store = Store.memory()
+    const { app, id } = await seed(store, 8)
+
+    const response = await app.v1.webhooks[':id{wh_[A-Za-z0-9_-]+}'].deliveries.$get(
+      { param: { id }, query: { include: 'totalCount', limit: '5' } },
+      as(writer),
+    )
+    const body = await TestApp.json(response, Webhooks.schema.listWebhookDeliveries.Response)
+    expect(response.status).toBe(200)
+    // The count is the full delivery total, independent of the page `limit`.
+    expect(body.data.length).toBe(5)
+    expect(body.meta).toEqual({ totalCountCapped: false, totalCount: 8 })
+
+    // Without the include, `meta` is omitted.
+    const bare = await app.v1.webhooks[':id{wh_[A-Za-z0-9_-]+}'].deliveries.$get(
+      { param: { id }, query: {} },
+      as(writer),
+    )
+    const bareBody = await TestApp.json(bare, Webhooks.schema.listWebhookDeliveries.Response)
+    expect(bareBody.meta).toBeUndefined()
+  })
+
+  test('paginates with cursor and limit', async () => {
+    const store = Store.memory()
+    const { app, id } = await seed(store, 6)
+
+    const first = await app.v1.webhooks[':id{wh_[A-Za-z0-9_-]+}'].deliveries.$get(
+      { param: { id }, query: { limit: '5' } },
+      as(writer),
+    )
+    const firstBody = await TestApp.json(first, Webhooks.schema.listWebhookDeliveries.Response)
+    expect(firstBody.data.map((d) => d.eventId)).toEqual([
+      'evt_6',
+      'evt_5',
+      'evt_4',
+      'evt_3',
+      'evt_2',
+    ])
+
+    const second = await app.v1.webhooks[':id{wh_[A-Za-z0-9_-]+}'].deliveries.$get(
+      { param: { id }, query: { cursor: firstBody.nextCursor!, limit: '5' } },
+      as(writer),
+    )
+    const secondBody = await TestApp.json(second, Webhooks.schema.listWebhookDeliveries.Response)
+    expect(secondBody.data.map((d) => d.eventId)).toEqual(['evt_1'])
+  })
+
+  test('serves a positional page via `page` (deterministic in-memory slice)', async () => {
+    const store = Store.memory()
+    const { app, id } = await seed(store, 6)
+
+    const response = await app.v1.webhooks[':id{wh_[A-Za-z0-9_-]+}'].deliveries.$get(
+      { param: { id }, query: { limit: '5', page: '2' } },
+      as(writer),
+    )
+    const body = await TestApp.json(response, Webhooks.schema.listWebhookDeliveries.Response)
+    expect(response.status).toMatchInlineSnapshot(`200`)
+    // Newest-first feed of evt_6..evt_1; page 2 at limit 5 holds the last row.
+    expect(body.data.map((d) => d.eventId)).toEqual(['evt_1'])
+  })
+
+  test('rejects `page` combined with `cursor`', async () => {
+    const store = Store.memory()
+    const { app, id } = await seed(store, 6)
+
+    const first = await app.v1.webhooks[':id{wh_[A-Za-z0-9_-]+}'].deliveries.$get(
+      { param: { id }, query: { limit: '5' } },
+      as(writer),
+    )
+    const firstBody = await TestApp.json(first, Webhooks.schema.listWebhookDeliveries.Response)
+
+    const response = await app.v1.webhooks[':id{wh_[A-Za-z0-9_-]+}'].deliveries.$get(
+      { param: { id }, query: { cursor: firstBody.nextCursor!, page: '2' } },
+      as(writer),
+    )
+    expect(response.status).toMatchInlineSnapshot(`400`)
+  })
+
+  test('a read-only key can list deliveries', async () => {
+    const store = Store.memory()
+    const { app, id } = await seed(store, 1)
+
+    const response = await app.v1.webhooks[':id{wh_[A-Za-z0-9_-]+}'].deliveries.$get(
+      { param: { id }, query: {} },
+      as(reader),
+    )
+    expect(response.status).toMatchInlineSnapshot(`200`)
+  })
+
+  test('a different org cannot read another org deliveries', async () => {
+    const store = Store.memory()
+    const { app, id } = await seed(store, 1)
+
+    const response = await app.v1.webhooks[':id{wh_[A-Za-z0-9_-]+}'].deliveries.$get(
+      { param: { id }, query: {} },
+      as(other),
+    )
+    expect(response.status).toMatchInlineSnapshot(`404`)
+  })
+
+  test('404s for an unknown subscription', async () => {
+    const app = client()
+    const response = await app.v1.webhooks[':id{wh_[A-Za-z0-9_-]+}'].deliveries.$get(
+      { param: { id: 'wh_missing' }, query: {} },
+      as(writer),
+    )
+    expect(response.status).toMatchInlineSnapshot(`404`)
+  })
+})
+
+describe('SSRF protection', () => {
+  test('rejects a non-https callback URL', async () => {
+    const response = await client().v1.webhooks.$post(
+      { json: { ...validBody, destination: { type: 'url', url: 'http://example.com/hook' } } },
+      as(writer),
+    )
+    const body = (await response.json()) as { error?: { code?: string } }
+
+    expect(response.status).toMatchInlineSnapshot(`400`)
+    expect(body.error?.code).toMatchInlineSnapshot(`"url_invalid"`)
+  })
+
+  test('rejects the cloud metadata host', async () => {
+    const response = await client().v1.webhooks.$post(
+      {
+        json: {
+          ...validBody,
+          destination: { type: 'url', url: 'https://169.254.169.254/latest/meta-data' },
+        },
+      },
+      as(writer),
+    )
+    const body = (await response.json()) as { error?: { code?: string } }
+
+    expect(response.status).toMatchInlineSnapshot(`400`)
+    expect(body.error?.code).toMatchInlineSnapshot(`"url_invalid"`)
+  })
+})
+
+describe('subscription context', () => {
+  test('round-trips context through create and read', async () => {
+    const app = TestApp.client({
+      auth: { source: TestApp.source({ keys: [writer] }) },
+      webhook: { store: Store.memory() },
+    })
+    const context = {
+      description: 'Notify #ops when a large USDC transfer settles.',
+      metadata: { env: 'prod', team: 'payments' },
+      title: 'Prod USDC large transfers',
+    }
+    const created = await app.v1.webhooks.$post(
+      {
+        json: {
+          context,
+          destination: { type: 'slack', url: 'https://hooks.slack.com/services/T000/B000/xxxx' },
+          eventType: 'token:transfer',
+        },
+      },
+      as(writer),
+    )
+    expect(created.status).toBe(200)
+    const body = await TestApp.json(created, Webhooks.schema.createWebhook.Response)
+    expect(body.context).toEqual(context)
+
+    const read = await app.v1.webhooks[':id{wh_[A-Za-z0-9_-]+}'].$get(
+      { param: { id: body.id } },
+      as(writer),
+    )
+    const readBody = await TestApp.json(read, Webhooks.schema.getWebhook.Response)
+    expect(readBody.context).toEqual(context)
+  })
+
+  test('clears context with an explicit null patch', async () => {
+    const app = TestApp.client({
+      auth: { source: TestApp.source({ keys: [writer] }) },
+      webhook: { store: Store.memory() },
+    })
+    const created = await app.v1.webhooks.$post(
+      {
+        json: {
+          context: { title: 'Temporary' },
+          destination: { type: 'slack', url: 'https://hooks.slack.com/services/T000/B000/xxxx' },
+          eventType: 'token:transfer',
+        },
+      },
+      as(writer),
+    )
+    const { id } = await TestApp.json(created, Webhooks.schema.createWebhook.Response)
+
+    const patched = await app.v1.webhooks[':id{wh_[A-Za-z0-9_-]+}'].$patch(
+      { json: { context: null }, param: { id } },
+      as(writer),
+    )
+    const body = await TestApp.json(patched, Webhooks.schema.updateWebhook.Response)
+    expect(body.context).toBeUndefined()
+  })
+
+  test('rejects metadata that exceeds the entry limit', async () => {
+    const app = TestApp.client({
+      auth: { source: TestApp.source({ keys: [writer] }) },
+      webhook: { store: Store.memory() },
+    })
+    const metadata = Object.fromEntries(Array.from({ length: 21 }, (_, i) => [`key${i}`, 'value']))
+    const created = await app.v1.webhooks.$post(
+      {
+        json: {
+          context: { metadata },
+          destination: { type: 'slack', url: 'https://hooks.slack.com/services/T000/B000/xxxx' },
+          eventType: 'token:transfer',
+        },
+      },
+      as(writer),
+    )
+    expect(created.status).toBe(400)
+  })
+})
+
+describe('slack destination', () => {
+  test('creates a subscription with a slack incoming-webhook URL', async () => {
+    const app = TestApp.client({
+      auth: { source: TestApp.source({ keys: [writer] }) },
+      webhook: { store: Store.memory() },
+    })
+    const created = await app.v1.webhooks.$post(
+      {
+        json: {
+          destination: {
+            type: 'slack',
+            url: 'https://hooks.slack.com/services/T000/B000/xxxx',
+          },
+          eventType: 'token:transfer',
+        },
+      },
+      as(writer),
+    )
+    expect(created.status).toMatchInlineSnapshot(`200`)
+    const body = await TestApp.json(created, Webhooks.schema.createWebhook.Response)
+    expect(body.destination).toMatchInlineSnapshot(`
+      {
+        "type": "slack",
+        "url": "https://hooks.slack.com/services/T000/B000/xxxx",
+      }
+    `)
+  })
+
+  test('rejects a slack destination whose host is not hooks.slack.com', async () => {
+    const app = TestApp.client({
+      auth: { source: TestApp.source({ keys: [writer] }) },
+      webhook: { store: Store.memory() },
+    })
+    const response = await app.v1.webhooks.$post(
+      {
+        json: {
+          destination: { type: 'slack', url: 'https://evil.example.com/hook' },
+          eventType: 'token:transfer',
+        },
+      },
+      as(writer),
+    )
+    const body = (await response.json()) as { error?: { code?: string } }
+
+    expect(response.status).toMatchInlineSnapshot(`400`)
+    expect(body.error?.code).toMatchInlineSnapshot(`"url_invalid"`)
+  })
+})
+
+describe('betterstack destination', () => {
+  test('creates a subscription with a Better Stack source', async () => {
+    const app = TestApp.client({
+      auth: { source: TestApp.source({ keys: [writer] }) },
+      webhook: { store: Store.memory() },
+    })
+    const created = await app.v1.webhooks.$post(
+      {
+        json: {
+          destination: {
+            token: 'src_token',
+            type: 'betterstack',
+            url: 'https://s1234567.eu-nbg-2.betterstackdata.com',
+          },
+          eventType: 'token:transfer',
+        },
+      },
+      as(writer),
+    )
+    expect(created.status).toMatchInlineSnapshot(`200`)
+    const body = await TestApp.json(created, Webhooks.schema.createWebhook.Response)
+    expect(body.destination).toMatchInlineSnapshot(`
+      {
+        "token": "src_token",
+        "type": "betterstack",
+        "url": "https://s1234567.eu-nbg-2.betterstackdata.com",
+      }
+    `)
+  })
+
+  test('rejects a Better Stack destination whose host is not betterstackdata.com', async () => {
+    const app = TestApp.client({
+      auth: { source: TestApp.source({ keys: [writer] }) },
+      webhook: { store: Store.memory() },
+    })
+    const response = await app.v1.webhooks.$post(
+      {
+        json: {
+          destination: {
+            token: 'src_token',
+            type: 'betterstack',
+            url: 'https://evil.example.com/ingest',
+          },
+          eventType: 'token:transfer',
+        },
+      },
+      as(writer),
+    )
+    const body = (await response.json()) as { error?: { code?: string } }
+
+    expect(response.status).toMatchInlineSnapshot(`400`)
+    expect(body.error?.code).toMatchInlineSnapshot(`"url_invalid"`)
+  })
+})
+
+describe('ping', () => {
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  /** Seeds a webhooks-enabled client with a subscription owned by `writer`. */
+  async function seed() {
+    const app = TestApp.client({
+      auth: { source: TestApp.source({ keys: [writer, reader, other] }) },
+      webhook: { store: Store.memory() },
+    })
+    const created = await app.v1.webhooks.$post({ json: validBody }, as(writer))
+    const { id } = await TestApp.json(created, Webhooks.schema.createWebhook.Response)
+    return { app, id }
+  }
+
+  test('delivers a synthetic ping and returns the result', async () => {
+    const { app, id } = await seed()
+
+    const calls: { signature: string | null }[] = []
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (_input, init) => {
+      calls.push({ signature: new Headers(init?.headers).get('tempo-signature') })
+      return new Response(null, { status: 200 })
+    })
+
+    const response = await app.v1.webhooks[':id{wh_[A-Za-z0-9_-]+}'].ping.$post(
+      { param: { id } },
+      as(writer),
+    )
+    expect(response.status).toMatchInlineSnapshot(`200`)
+    const body = await TestApp.json(response, Webhooks.schema.pingWebhook.Response)
+    expect(body.delivered).toMatchInlineSnapshot(`true`)
+    expect(body.responseStatus).toMatchInlineSnapshot(`200`)
+    expect(body.eventId).toMatch(/^evt_[0-9a-f]{64}$/)
+
+    // A single signed request reached the endpoint.
+    expect(calls).toHaveLength(1)
+    expect(calls[0]?.signature).toBeTruthy()
+
+    // The ping is observable in the delivery log under the same event id.
+    const deliveries = await app.v1.webhooks[':id{wh_[A-Za-z0-9_-]+}'].deliveries.$get(
+      { param: { id }, query: {} },
+      as(writer),
+    )
+    const log = await TestApp.json(deliveries, Webhooks.schema.listWebhookDeliveries.Response)
+    expect(log.data).toHaveLength(1)
+    expect(log.data[0]?.eventId).toBe(body.eventId)
+  })
+
+  test('reports a failed delivery without disabling the subscription', async () => {
+    const { app, id } = await seed()
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response(null, { status: 500 }))
+
+    const response = await app.v1.webhooks[':id{wh_[A-Za-z0-9_-]+}'].ping.$post(
+      { param: { id } },
+      as(writer),
+    )
+    const body = await TestApp.json(response, Webhooks.schema.pingWebhook.Response)
+    expect(body.delivered).toMatchInlineSnapshot(`false`)
+    expect(body.error).toMatchInlineSnapshot(`"non-2xx response (500)"`)
+
+    // A failed test ping must leave a healthy subscription active.
+    const read = await app.v1.webhooks[':id{wh_[A-Za-z0-9_-]+}'].$get({ param: { id } }, as(writer))
+    const subscription = await TestApp.json(read, Webhooks.schema.getWebhook.Response)
+    expect(subscription.status).toMatchInlineSnapshot(`"active"`)
+    expect(subscription.failureCount).toMatchInlineSnapshot(`0`)
+  })
+
+  test('a read-only key cannot ping', async () => {
+    const { app, id } = await seed()
+    const response = await app.v1.webhooks[':id{wh_[A-Za-z0-9_-]+}'].ping.$post(
+      { param: { id } },
+      as(reader),
+    )
+    expect(response.status).toMatchInlineSnapshot(`403`)
+  })
+
+  test('a different org cannot ping another org subscription', async () => {
+    const { app, id } = await seed()
+    const response = await app.v1.webhooks[':id{wh_[A-Za-z0-9_-]+}'].ping.$post(
+      { param: { id } },
+      as(other),
+    )
+    expect(response.status).toMatchInlineSnapshot(`404`)
+  })
+
+  test('404s for an unknown subscription', async () => {
+    const app = client()
+    const response = await app.v1.webhooks[':id{wh_[A-Za-z0-9_-]+}'].ping.$post(
+      { param: { id: 'wh_missing' } },
+      as(writer),
+    )
+    expect(response.status).toMatchInlineSnapshot(`404`)
+  })
+})
+
+describe('retry delivery', () => {
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  const deliveryId = 'whd_001700000000000_0000000000000000'
+
+  /** Seeds a webhooks client with a subscription plus one logged delivery to replay. */
+  async function seed() {
+    const store = Store.memory()
+    const app = TestApp.client({
+      auth: { source: TestApp.source({ keys: [writer, reader, other] }) },
+      webhook: { store },
+    })
+    const created = await app.v1.webhooks.$post({ json: validBody }, as(writer))
+    const { id } = await TestApp.json(created, Webhooks.schema.createWebhook.Response)
+    await Core.recordDelivery(store, {
+      attempt: 1,
+      createdAt: new Date(1_700_000_000_000).toISOString(),
+      envelope: {
+        chainId: 4217,
+        createdAt: new Date(1_700_000_000_000).toISOString(),
+        data: { amount: '1' },
+        id: 'evt_seed',
+        subscriptionId: id,
+        type: 'token:transfer',
+      },
+      eventId: 'evt_seed',
+      id: deliveryId,
+      requestUrl: 'https://example.com/hook',
+      status: 'failed',
+      subscriptionId: id,
+    })
+    return { app, id, store }
+  }
+
+  test('replays the stored envelope and records a new attempt', async () => {
+    const { app, id, store } = await seed()
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response(null, { status: 200 }))
+
+    const response = await app.v1.webhooks[':id{wh_[A-Za-z0-9_-]+}'].deliveries[
+      ':deliveryId'
+    ].retry.$post({ param: { deliveryId, id } }, as(writer))
+    expect(response.status).toMatchInlineSnapshot(`200`)
+    const body = await TestApp.json(response, Webhooks.schema.retryWebhookDelivery.Response)
+    expect(body.delivered).toMatchInlineSnapshot(`true`)
+    expect(body.eventId).toMatchInlineSnapshot(`"evt_seed"`)
+
+    // A new attempt was appended alongside the seeded row.
+    expect(await Core.listDeliveries(store, id)).toHaveLength(2)
+  })
+
+  test('a failed replay reports the error', async () => {
+    const { app, id } = await seed()
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response(null, { status: 500 }))
+
+    const response = await app.v1.webhooks[':id{wh_[A-Za-z0-9_-]+}'].deliveries[
+      ':deliveryId'
+    ].retry.$post({ param: { deliveryId, id } }, as(writer))
+    const body = await TestApp.json(response, Webhooks.schema.retryWebhookDelivery.Response)
+    expect(body.delivered).toMatchInlineSnapshot(`false`)
+    expect(body.error).toMatchInlineSnapshot(`"non-2xx response (500)"`)
+  })
+
+  test('a read-only key cannot retry', async () => {
+    const { app, id } = await seed()
+    const response = await app.v1.webhooks[':id{wh_[A-Za-z0-9_-]+}'].deliveries[
+      ':deliveryId'
+    ].retry.$post({ param: { deliveryId, id } }, as(reader))
+    expect(response.status).toMatchInlineSnapshot(`403`)
+  })
+
+  test('a different org cannot retry another org delivery', async () => {
+    const { app, id } = await seed()
+    const response = await app.v1.webhooks[':id{wh_[A-Za-z0-9_-]+}'].deliveries[
+      ':deliveryId'
+    ].retry.$post({ param: { deliveryId, id } }, as(other))
+    expect(response.status).toMatchInlineSnapshot(`404`)
+  })
+
+  test('404s with delivery_not_found for an unknown delivery', async () => {
+    const { app, id } = await seed()
+    const response = await app.v1.webhooks[':id{wh_[A-Za-z0-9_-]+}'].deliveries[
+      ':deliveryId'
+    ].retry.$post({ param: { deliveryId: 'whd_missing', id } }, as(writer))
+    expect(response.status).toMatchInlineSnapshot(`404`)
+    const body = (await response.json()) as { error?: { code?: string } }
+    expect(body.error?.code).toMatchInlineSnapshot(`"delivery_not_found"`)
+  })
+
+  test('404s for an unknown subscription', async () => {
+    const app = client()
+    const response = await app.v1.webhooks[':id{wh_[A-Za-z0-9_-]+}'].deliveries[
+      ':deliveryId'
+    ].retry.$post({ param: { deliveryId: 'whd_x', id: 'wh_missing' } }, as(writer))
+    expect(response.status).toMatchInlineSnapshot(`404`)
+  })
+})
+
+describe('OpenAPI visibility', () => {
+  test('hides webhook routes when the feature is disabled', async () => {
+    const app = TestApp.create({ auth: { source: TestApp.source({ keys: [writer] }) } })
+    const body = (await (await app.request('/openapi.json')).json()) as { paths: object }
+
+    // OpenAPI paths include App.create's mounted `/v1` prefix; the webhook
+    // sub-app's local `/webhooks` paths are not emitted prefix-free.
+    expect(Object.keys(body.paths).some((path) => path.startsWith('/v1/webhooks'))).toBe(false)
+  })
+
+  test('documents webhook routes when the feature is enabled', async () => {
+    const app = TestApp.create({
+      auth: { source: TestApp.source({ keys: [writer] }) },
+      webhook: { store: Store.memory() },
+    })
+    const body = (await (await app.request('/openapi.json')).json()) as { paths: object }
+    const paths = Object.keys(body.paths)
+      .filter((path) => path.startsWith('/v1/webhooks'))
+      .sort()
+
+    expect(paths).toMatchInlineSnapshot(`
+      [
+        "/v1/webhooks",
+        "/v1/webhooks/event-types",
+        "/v1/webhooks/{id}",
+        "/v1/webhooks/{id}/deliveries",
+        "/v1/webhooks/{id}/deliveries/{deliveryId}/retry",
+        "/v1/webhooks/{id}/ping",
+      ]
+    `)
+  })
+
+  test('omits the outbound `webhooks` section when the feature is disabled', async () => {
+    const app = TestApp.create({ auth: { source: TestApp.source({ keys: [writer] }) } })
+    const body = (await (await app.request('/openapi.json')).json()) as { webhooks?: object }
+
+    expect(body.webhooks).toMatchInlineSnapshot(`undefined`)
+  })
+
+  test('documents the outbound delivery envelope under OAS `webhooks` when enabled', async () => {
+    const app = TestApp.create({
+      auth: { source: TestApp.source({ keys: [writer] }) },
+      webhook: { store: Store.memory() },
+    })
+    const body = (await (await app.request('/openapi.json')).json()) as {
+      webhooks?: {
+        event?: {
+          post?: {
+            parameters?: { name: string }[]
+            requestBody?: {
+              content?: { 'application/json'?: { schema?: { oneOf?: { title?: string }[] } } }
+            }
+          }
+        }
+      }
+    }
+
+    expect(body.webhooks?.event?.post?.parameters?.map((p) => p.name)).toMatchInlineSnapshot(`
+      [
+        "tempo-signature",
+        "tempo-event-id",
+        "tempo-event-type",
+      ]
+    `)
+    // Each envelope variant carries a `title` so Scalar renders a labelled
+    // variant selector rather than collapsing the union to its first member.
+    const variants =
+      body.webhooks?.event?.post?.requestBody?.content?.['application/json']?.schema?.oneOf
+    expect(variants?.map((v) => v.title)).toMatchInlineSnapshot(`
+      [
+        "Transfer event",
+        "Included transaction event",
+        "Log event",
+        "Block event",
+        "Ping (test delivery)",
+      ]
+    `)
+  })
+
+  test('documents per-event-type filters on the create body', async () => {
+    const app = TestApp.create({
+      auth: { source: TestApp.source({ keys: [writer] }) },
+      webhook: { store: Store.memory() },
+    })
+    const body = (await (await app.request('/openapi.json')).json()) as {
+      paths: {
+        '/v1/webhooks': {
+          post: {
+            requestBody: {
+              content: {
+                'application/json': {
+                  schema: {
+                    oneOf?: {
+                      title?: string
+                      properties?: { filters?: { properties?: Record<string, unknown> } }
+                    }[]
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+    const variants =
+      body.paths['/v1/webhooks'].post.requestBody.content['application/json'].schema.oneOf
+
+    // Each event type renders as a titled variant exposing only its own filters.
+    expect(
+      variants?.map((v) => ({
+        filters: Object.keys(v.properties?.filters?.properties ?? {}),
+        title: v.title,
+      })),
+    ).toMatchInlineSnapshot(`
+      [
+        {
+          "filters": [
+            "address",
+            "recipient",
+            "sender",
+            "token",
+          ],
+          "title": "Transfer subscription",
+        },
+        {
+          "filters": [
+            "hash",
+            "address",
+            "from",
+            "to",
+            "includeCalls",
+            "includeReceipt",
+            "value",
+            "input",
+            "calls",
+            "callCount",
+            "txType",
+            "feeToken",
+            "feePayer",
+            "gasLimit",
+            "gasUsed",
+            "maxFeePerGas",
+            "maxPriorityFeePerGas",
+            "nonce",
+            "nonceKey",
+            "validBefore",
+            "validAfter",
+            "blockNumber",
+            "timestamp",
+            "status",
+          ],
+          "title": "Included-transaction subscription",
+        },
+        {
+          "filters": [
+            "address",
+            "signature",
+            "topic0",
+            "topic1",
+            "topic2",
+            "topic3",
+            "args",
+            "blockNumber",
+          ],
+          "title": "Log subscription",
+        },
+        {
+          "filters": [
+            "number",
+            "miner",
+            "proposer",
+            "gasUsed",
+            "gasLimit",
+            "timestamp",
+          ],
+          "title": "Block subscription",
+        },
+      ]
+    `)
+  })
+})
+
+describe('envelope schema', () => {
+  /** A `transfer` subscription used to build representative envelopes. */
+  async function transferSubscription() {
+    const store = Store.memory()
+    return Core.buildEnvelope({
+      blockNumber: 100,
+      createdAt: new Date('2026-01-01T00:00:00.000Z'),
+      data: {
+        address: '0x20c0000000000000000000008f5425160ebe5525',
+        amount: '1000',
+        blockNumber: 100,
+        recipient: '0x2222222222222222222222222222222222222222',
+        sender: '0x1111111111111111111111111111111111111111',
+        timestamp: '2026-01-01T00:00:00.000Z',
+        transactionHash: '0x33333333333333333333333333333333333333333333333333333333333333aa',
+      },
+      logIndex: 0,
+      subscription: await Core.createSubscription(store, {
+        chainId: 42431,
+        eventType: 'token:transfer',
+        owner: { orgId: 'org_test', type: 'api_key' },
+        destination: { type: 'url', url: 'https://hooks.example.com/x' },
+      }),
+    })
+  }
+
+  test('round-trips a delivered transfer envelope', async () => {
+    const parsed = Webhooks.schema.Envelope.safeParse(await transferSubscription())
+
+    expect(parsed.success).toMatchInlineSnapshot(`true`)
+  })
+
+  test('round-trips a ping envelope', async () => {
+    const store = Store.memory()
+    const subscription = await Core.createSubscription(store, {
+      chainId: 42431,
+      eventType: 'token:transfer',
+      owner: { orgId: 'org_test', type: 'api_key' },
+      destination: { type: 'url', url: 'https://hooks.example.com/x' },
+    })
+    const parsed = Webhooks.schema.Envelope.safeParse(Core.buildPingEnvelope(subscription))
+
+    expect(parsed.success).toMatchInlineSnapshot(`true`)
+    expect(parsed.success && parsed.data.type).toMatchInlineSnapshot(`"ping"`)
+  })
+
+  test('rejects an unknown envelope type', () => {
+    const parsed = Webhooks.schema.Envelope.safeParse({
+      chainId: 42431,
+      createdAt: '2026-01-01T00:00:00.000Z',
+      data: {},
+      id: 'evt_x',
+      subscriptionId: 'wh_x',
+      type: 'unknown',
+    })
+
+    expect(parsed.success).toMatchInlineSnapshot(`false`)
+  })
+})
+
+describe('MPP access (disabled for now — API-key-only)', () => {
+  test('rejects an MPP payer with 401, offering no payment challenge', async () => {
+    const app = TestApp.create({
+      auth: { source: TestApp.source({ keys: [] }) },
+      mpp: {
+        charge: {
+          chainId: Tempo.chain.id,
+          currency: Tempo.currency,
+          decimals: 6,
+          getClient: () => Tempo.client,
+          recipient: Tempo.accounts[2].address,
+        },
+        secretKey: 'secret_test_key_0123456789abcdef',
+      },
+      webhook: { store: Store.memory() },
+    })
+
+    // The paid lane is disabled on webhook routes, so no `402` challenge is
+    // offered: the MPP client's request is rejected outright (`401`) and never
+    // gets a chance to pay, so no payment receipt is issued.
+    const response = await Mppx.createClient(app).fetch('http://tempo-api.test/v1/webhooks', {
+      body: JSON.stringify(validBody),
+      headers: { 'content-type': 'application/json' },
+      method: 'POST',
+    })
+
+    expect(response.status).toMatchInlineSnapshot(`401`)
+    expect(response.headers.has('payment-receipt')).toMatchInlineSnapshot(`false`)
+  })
+})
+
+// The poll tests pin a FIXED immutable historical window on testnet chain 42431
+// (real TIDX + `rpc.testnet.tempo.xyz`). Under `localnet`, the test RPC client is
+// redirected to the disposable local chain, which lacks that history, so the
+// whole block is testnet-only.
+describe.skipIf(Runtime.get().mode === 'localnet')('poll', () => {
+  /** Decodes the opaque `(block, index)` keyset cursor the poller stores. */
+  function decodeCursor(token: string | null): [number, number] | null {
+    if (!token) return null
+    const json = atob(token.replaceAll('-', '+').replaceAll('_', '/'))
+    return JSON.parse(json) as [number, number]
+  }
+
+  /** Encodes a `(block, index)` keyset cursor in the poller's opaque format. */
+  function encodeCursor(values: [number, number]): string {
+    return btoa(JSON.stringify(values)).replaceAll('+', '-').replaceAll('/', '_').replace(/=+$/, '')
+  }
+
+  /** End-of-block index sentinel (matches the poller's own cursor sentinel). */
+  const endOfBlockIndex = 2_147_483_647
+
+  // The poller scans real TIDX, so the tests pin a FIXED historical block window
+  // on chain 42431. Chain history is immutable, so a narrow `sender` filter over
+  // this window yields a deterministic, snapshot-stable row set while exercising
+  // the real keyset/`toBlock` SQL and decode path end to end — no fabricated rows.
+  const realTidx = Tidx.getClient({
+    chainId: 42431,
+    tidx: { baseUrl: 'https://tidx.tempo.xyz', basicAuth: process.env.VITE_TIDX_BASIC_AUTH },
+  })
+  // The monitoring scanners (`log:emitted`/`block:created`/`transaction:included`)
+  // read the same immutable historical window over real RPC (chain 42431 →
+  // `rpc.testnet.tempo.xyz`), so their results are snapshot-stable too.
+  const client = Viem.getClient({ chainId: 42431, rpc: TestApp.rpc })
+  // Confirmed scan window `[windowFrom, windowTo]`: anchor the cursor just below
+  // `windowFrom`, and pass `headBlockNumber = windowTo + confirmations` so the
+  // poller's `safeBlock` lands exactly on `windowTo`.
+  const windowFrom = 1_000_000
+  const windowTo = 1_000_002
+  const windowCursor = encodeCursor([windowFrom - 1, endOfBlockIndex])
+  const windowHead = windowTo + 2
+  // A sender whose only transfers in `[windowFrom, windowTo]` are exactly two
+  // rows, both in block 1,000,002 (`log_idx` 0 then 1): a TIP-20 transfer
+  // followed by its fee payment. Filtering on it makes the scan deterministic.
+  const windowSender = '0xe7687128b0a808c2831ff94d4f7b2fb35c65af38'
+
+  async function createTransferSubscription(store: ReturnType<typeof Store.memory>) {
+    return Core.createSubscription(store, {
+      chainId: 42431,
+      eventType: 'token:transfer',
+      filters: { sender: windowSender },
+      owner: { orgId: 'org_test', type: 'api_key' },
+      destination: { type: 'url', url: 'https://hooks.example.com/x' },
+    })
+  }
+
+  test('dispatches a signed envelope per row and advances the cursor', async () => {
+    const store = Store.memory()
+    const subscription = await createTransferSubscription(store)
+    // Anchor the subscription just below the pinned window so the poller scans
+    // it this tick (a brand-new subscription anchors at head and skips its first
+    // tick).
+    await Core.setCursor(store, subscription.id, windowCursor)
+
+    const dispatched: Webhooks.poll.Dispatchable[] = []
+    const result = await Webhooks.poll({
+      chainId: 42431,
+      dispatch: async (input) => {
+        dispatched.push(input)
+        return { ok: true }
+      },
+      eventTypes: ['token:transfer'],
+      headBlockNumber: windowHead,
+      client,
+      store,
+      tidx: realTidx,
+    })
+
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "chainId": 42431,
+        "dispatched": 2,
+        "failed": 0,
+        "safeBlock": 1000002,
+        "scanned": 2,
+        "subscriptions": 1,
+      }
+    `)
+    expect(dispatched).toHaveLength(2)
+    // The envelope carries the read-endpoint transfer row verbatim — here the
+    // first of the two pinned-window transfers from `windowSender`.
+    expect(dispatched[0]?.envelope.data).toMatchInlineSnapshot(`
+      {
+        "address": "0x20c00000000000000000000071de0cd31ab0d105",
+        "amount": "10000",
+        "blockNumber": 1000002,
+        "logIndex": 0,
+        "recipient": "0x9e39034aae71fb89f66061a2602eb6efec271754",
+        "sender": "0xe7687128b0a808c2831ff94d4f7b2fb35c65af38",
+        "timestamp": "2026-01-14T18:38:03.000Z",
+        "token": {
+          "decimals": 6,
+          "symbol": "QKSUSD",
+        },
+        "transactionHash": "0x3d24a706cc2f6f4c96620bef1f61ddb23040ff77c22c8db42918c7c424bbf9d3",
+      }
+    `)
+
+    // Cursor advanced to the last dispatched row `(1000002, 1)`.
+    expect(decodeCursor(await Core.getCursor(store, subscription.id))).toMatchInlineSnapshot(`
+      [
+        1000002,
+        1,
+      ]
+    `)
+  })
+
+  test('pauses the cursor at the last success when dispatch fails', async () => {
+    const store = Store.memory()
+    const subscription = await createTransferSubscription(store)
+    await Core.setCursor(store, subscription.id, windowCursor)
+
+    let calls = 0
+    const result = await Webhooks.poll({
+      chainId: 42431,
+      // Succeed on the first row, fail on the second.
+      dispatch: async () => (++calls === 1 ? { ok: true } : { error: 'boom', ok: false }),
+      eventTypes: ['token:transfer'],
+      headBlockNumber: windowHead,
+      client,
+      store,
+      tidx: realTidx,
+    })
+
+    expect(result.dispatched).toMatchInlineSnapshot(`1`)
+    expect(result.failed).toMatchInlineSnapshot(`1`)
+
+    // Cursor stops at the first (successful) row `(1000002, 0)`, so the failed
+    // one re-runs on the next tick (at-least-once).
+    expect(decodeCursor(await Core.getCursor(store, subscription.id))).toMatchInlineSnapshot(`
+      [
+        1000002,
+        0,
+      ]
+    `)
+  })
+
+  test('does not advance the cursor when the first row fails', async () => {
+    const store = Store.memory()
+    const subscription = await createTransferSubscription(store)
+    await Core.setCursor(store, subscription.id, windowCursor)
+
+    const result = await Webhooks.poll({
+      chainId: 42431,
+      dispatch: async () => ({ error: 'unreachable', ok: false }),
+      eventTypes: ['token:transfer'],
+      headBlockNumber: windowHead,
+      client,
+      store,
+      tidx: realTidx,
+    })
+
+    expect(result.dispatched).toMatchInlineSnapshot(`0`)
+    expect(result.failed).toMatchInlineSnapshot(`1`)
+    // Nothing accepted → cursor untouched at the window anchor, so the row
+    // retries next tick.
+    expect(decodeCursor(await Core.getCursor(store, subscription.id))).toMatchInlineSnapshot(`
+      [
+        999999,
+        2147483647,
+      ]
+    `)
+  })
+
+  test('anchors a first-seen subscription at the confirmed head without backfilling', async () => {
+    const store = Store.memory()
+    const subscription = await createTransferSubscription(store)
+
+    const dispatched: Webhooks.poll.Dispatchable[] = []
+    const result = await Webhooks.poll({
+      chainId: 42431,
+      dispatch: async (input) => {
+        dispatched.push(input)
+        return { ok: true }
+      },
+      eventTypes: ['token:transfer'],
+      headBlockNumber: windowHead,
+      client,
+      store,
+      // Rows exist in history, but a brand-new subscription must not replay them.
+      tidx: realTidx,
+    })
+
+    // Nothing scanned or dispatched on the first tick; the cursor is anchored at
+    // the head of the confirmed window (`windowHead - confirmations` = 1000002).
+    expect(result.scanned).toMatchInlineSnapshot(`0`)
+    expect(dispatched).toHaveLength(0)
+    expect(decodeCursor(await Core.getCursor(store, subscription.id))).toMatchInlineSnapshot(`
+      [
+        1000002,
+        2147483647,
+      ]
+    `)
+  })
+
+  test('advances to the end of the confirmed window on an empty scan', async () => {
+    const store = Store.memory()
+    const subscription = await createTransferSubscription(store)
+    // Anchor just past the window's only matching block (1000002) and confirm up
+    // to block 1000004 — a range `windowSender` has no transfers in, so the scan
+    // is genuinely empty.
+    await Core.setCursor(store, subscription.id, encodeCursor([windowTo, endOfBlockIndex]))
+
+    const result = await Webhooks.poll({
+      chainId: 42431,
+      dispatch: async () => ({ ok: true }),
+      eventTypes: ['token:transfer'],
+      headBlockNumber: windowTo + 4,
+      client,
+      store,
+      tidx: realTidx,
+    })
+
+    expect(result.scanned).toMatchInlineSnapshot(`0`)
+
+    // No rows, clean scan: cursor jumps past the end of the confirmed window
+    // (`headBlockNumber - confirmations` = block 1000004) so it is not rescanned.
+    expect(decodeCursor(await Core.getCursor(store, subscription.id))).toMatchInlineSnapshot(`
+      [
+        1000004,
+        2147483647,
+      ]
+    `)
+  })
+
+  // The two pinned-window rows are `Transfer(from, to, value)` logs. Their raw
+  // topic0 (the `Transfer` selector) and the `from` address padded to a bytes32
+  // topic let the raw-log path be filtered as deterministically as the decoded
+  // path.
+  const transferSignature =
+    'event Transfer(address indexed from, address indexed to, uint256 value)'
+  const transferSelector = '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'
+  const windowSenderTopic = `0x${'0'.repeat(24)}${windowSender.slice(2)}`
+
+  test('log:emitted decodes args from a signature-matched event view', async () => {
+    const store = Store.memory()
+    const subscription = await Core.createSubscription(store, {
+      chainId: 42431,
+      eventType: 'log:emitted',
+      filters: { signature: transferSignature, args: { from: windowSender } },
+      owner: { orgId: 'org_test', type: 'api_key' },
+      destination: { type: 'url', url: 'https://hooks.example.com/x' },
+    })
+    await Core.setCursor(store, subscription.id, windowCursor)
+
+    const dispatched: Webhooks.poll.Dispatchable[] = []
+    const result = await Webhooks.poll({
+      chainId: 42431,
+      dispatch: async (input) => {
+        dispatched.push(input)
+        return { ok: true }
+      },
+      eventTypes: ['log:emitted'],
+      headBlockNumber: windowHead,
+      client,
+      store,
+      tidx: realTidx,
+    })
+
+    expect(result.scanned).toMatchInlineSnapshot(`2`)
+    expect(dispatched[0]?.envelope.data).toMatchInlineSnapshot(`
+      {
+        "address": "0x20c00000000000000000000071de0cd31ab0d105",
+        "args": {
+          "from": "0xE7687128b0A808C2831ff94d4F7B2fb35C65aF38",
+          "to": "0x9E39034aAE71fb89f66061a2602eb6eFeC271754",
+          "value": "10000",
+        },
+        "blockNumber": 1000002,
+        "data": "0x0000000000000000000000000000000000000000000000000000000000002710",
+        "event": {
+          "name": "Transfer",
+          "signature": "event Transfer(address indexed from, address indexed to, uint256 value)",
+          "topic0": "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
+        },
+        "logIndex": 0,
+        "timestamp": "2026-01-14T18:38:03.000Z",
+        "topics": [
+          "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
+          "0x000000000000000000000000e7687128b0a808c2831ff94d4f7b2fb35c65af38",
+          "0x0000000000000000000000009e39034aae71fb89f66061a2602eb6efec271754",
+        ],
+        "transactionHash": "0x3d24a706cc2f6f4c96620bef1f61ddb23040ff77c22c8db42918c7c424bbf9d3",
+        "transactionIndex": 0,
+      }
+    `)
+  })
+
+  test('log:emitted scans raw logs by topic when no signature is given', async () => {
+    const store = Store.memory()
+    const subscription = await Core.createSubscription(store, {
+      chainId: 42431,
+      eventType: 'log:emitted',
+      filters: { topic0: transferSelector, topic1: windowSenderTopic },
+      owner: { orgId: 'org_test', type: 'api_key' },
+      destination: { type: 'url', url: 'https://hooks.example.com/x' },
+    })
+    await Core.setCursor(store, subscription.id, windowCursor)
+
+    const dispatched: Webhooks.poll.Dispatchable[] = []
+    const result = await Webhooks.poll({
+      chainId: 42431,
+      dispatch: async (input) => {
+        dispatched.push(input)
+        return { ok: true }
+      },
+      eventTypes: ['log:emitted'],
+      headBlockNumber: windowHead,
+      client,
+      store,
+      tidx: realTidx,
+    })
+
+    expect(result.scanned).toMatchInlineSnapshot(`2`)
+    expect(dispatched[0]?.envelope.data).toMatchInlineSnapshot(`
+      {
+        "address": "0x20c00000000000000000000071de0cd31ab0d105",
+        "blockNumber": 1000002,
+        "data": "0x0000000000000000000000000000000000000000000000000000000000002710",
+        "logIndex": 0,
+        "timestamp": "2026-01-14T18:38:03.000Z",
+        "topics": [
+          "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
+          "0x000000000000000000000000e7687128b0a808c2831ff94d4f7b2fb35c65af38",
+          "0x0000000000000000000000009e39034aae71fb89f66061a2602eb6efec271754",
+        ],
+        "transactionHash": "0x3d24a706cc2f6f4c96620bef1f61ddb23040ff77c22c8db42918c7c424bbf9d3",
+        "transactionIndex": 0,
+      }
+    `)
+  })
+
+  test('block:created scans new blocks and resolves transaction counts', async () => {
+    const store = Store.memory()
+    const subscription = await Core.createSubscription(store, {
+      chainId: 42431,
+      eventType: 'block:created',
+      // Pin to a single block so the heartbeat feed is deterministic.
+      filters: { number: { eq: `0x${windowTo.toString(16)}` } },
+      owner: { orgId: 'org_test', type: 'api_key' },
+      destination: { type: 'url', url: 'https://hooks.example.com/x' },
+    })
+    await Core.setCursor(store, subscription.id, windowCursor)
+
+    const dispatched: Webhooks.poll.Dispatchable[] = []
+    const result = await Webhooks.poll({
+      chainId: 42431,
+      dispatch: async (input) => {
+        dispatched.push(input)
+        return { ok: true }
+      },
+      eventTypes: ['block:created'],
+      headBlockNumber: windowHead,
+      client,
+      store,
+      tidx: realTidx,
+    })
+
+    expect(result.scanned).toMatchInlineSnapshot(`1`)
+    expect(dispatched[0]?.envelope.data).toMatchInlineSnapshot(`
+      {
+        "gasLimit": 500000000,
+        "gasUsed": 4340281,
+        "hash": "0x3fe7d9e595f3d8215ec840c6ef55ac0bead58933e96fc2ead0f2aaf79715f45d",
+        "miner": "0x0000000000000000000000000000000000000000",
+        "number": 1000002,
+        "parentHash": "0xa406dff9c51cc2abbef3a811f0499e99a568bf781019f129ab45dca1df0e43e5",
+        "timestamp": "2026-01-14T18:38:03.000Z",
+        "transactionCount": 52,
+      }
+    `)
+    // The window scanner advances to the end of the fully-scanned block so the
+    // next tick resumes at the following block.
+    expect(decodeCursor(await Core.getCursor(store, subscription.id))).toMatchInlineSnapshot(`
+      [
+        1000002,
+        2147483647,
+      ]
+    `)
+  })
+
+  test('transaction:included filters on txs columns and inner calls', async () => {
+    const store = Store.memory()
+    const subscription = await Core.createSubscription(store, {
+      chainId: 42431,
+      eventType: 'transaction:included',
+      // `from` + an `input` selector (ERC20 `transfer` = 0xa9059cbb) pins the
+      // scan to the deterministic window tx.
+      filters: { from: windowSender, input: { selector: '0xa9059cbb' } },
+      owner: { orgId: 'org_test', type: 'api_key' },
+      destination: { type: 'url', url: 'https://hooks.example.com/x' },
+    })
+    await Core.setCursor(store, subscription.id, windowCursor)
+
+    const dispatched: Webhooks.poll.Dispatchable[] = []
+    const result = await Webhooks.poll({
+      chainId: 42431,
+      dispatch: async (input) => {
+        dispatched.push(input)
+        return { ok: true }
+      },
+      eventTypes: ['transaction:included'],
+      headBlockNumber: windowHead,
+      client,
+      store,
+      tidx: realTidx,
+    })
+
+    expect(result.scanned).toMatchInlineSnapshot(`1`)
+    const tx = dispatched[0]?.envelope.data as { hash: string; sender: string } | undefined
+    expect(tx?.hash).toMatchInlineSnapshot(
+      `"0x3d24a706cc2f6f4c96620bef1f61ddb23040ff77c22c8db42918c7c424bbf9d3"`,
+    )
+    expect(tx?.sender).toBe(windowSender)
+  })
+
+  test('transaction:included routes a status filter through receipts', async () => {
+    const store = Store.memory()
+    const subscription = await Core.createSubscription(store, {
+      chainId: 42431,
+      eventType: 'transaction:included',
+      filters: { from: windowSender, status: 'success' },
+      owner: { orgId: 'org_test', type: 'api_key' },
+      destination: { type: 'url', url: 'https://hooks.example.com/x' },
+    })
+    await Core.setCursor(store, subscription.id, windowCursor)
+
+    const result = await Webhooks.poll({
+      chainId: 42431,
+      dispatch: async () => ({ ok: true }),
+      eventTypes: ['transaction:included'],
+      headBlockNumber: windowHead,
+      client,
+      store,
+      tidx: realTidx,
+    })
+
+    // The window tx succeeded, so the status=success subquery keeps it.
+    expect(result.scanned).toMatchInlineSnapshot(`1`)
+  })
+
+  test('transaction:included embeds the receipt when includeReceipt is set', async () => {
+    const store = Store.memory()
+    const subscription = await Core.createSubscription(store, {
+      chainId: 42431,
+      eventType: 'transaction:included',
+      // No receipt-touching filter — `includeReceipt` alone must trigger the
+      // fetch and embed it in the delivered payload.
+      filters: { from: windowSender, input: { selector: '0xa9059cbb' }, includeReceipt: true },
+      owner: { orgId: 'org_test', type: 'api_key' },
+      destination: { type: 'url', url: 'https://hooks.example.com/x' },
+    })
+    await Core.setCursor(store, subscription.id, windowCursor)
+
+    const dispatched: Webhooks.poll.Dispatchable[] = []
+    const result = await Webhooks.poll({
+      chainId: 42431,
+      dispatch: async (input) => {
+        dispatched.push(input)
+        return { ok: true }
+      },
+      eventTypes: ['transaction:included'],
+      headBlockNumber: windowHead,
+      client,
+      store,
+      tidx: realTidx,
+    })
+
+    expect(result.scanned).toMatchInlineSnapshot(`1`)
+    const data = dispatched[0]?.envelope.data as
+      | { hash: string; meta?: { receipt?: { status: string; transactionHash: string } } }
+      | undefined
+    // The receipt is embedded under `meta.receipt`, matching the read endpoint's
+    // `include=receipt` shape, and refers to the same transaction.
+    expect(data?.meta?.receipt?.status).toMatchInlineSnapshot(`"success"`)
+    expect(data?.meta?.receipt?.transactionHash).toBe(data?.hash)
+  })
+
+  // End-to-end through the *default* transport: `poll` with no injected
+  // `dispatch` falls back to `deliverAndRecord`, which signs and POSTs via
+  // `globalThis.fetch` and records the outcome. These stub the global fetch so a
+  // seeded TIDX row reaches a captured local sink with no network.
+  describe('default transport (deliverAndRecord)', () => {
+    afterEach(() => {
+      vi.restoreAllMocks()
+    })
+
+    test('delivers a verifiable signed envelope and records success', async () => {
+      const store = Store.memory()
+      const subscription = await createTransferSubscription(store)
+      await Core.setCursor(store, subscription.id, windowCursor)
+
+      // Real TIDX queries also go through `globalThis.fetch`, so the mock passes
+      // non-webhook requests through to the real network and only captures the
+      // delivery POST to the subscription URL.
+      const realFetch = globalThis.fetch.bind(globalThis)
+      const calls: { body: string; headers: Headers; url: string }[] = []
+      vi.spyOn(globalThis, 'fetch').mockImplementation(async (input, init) => {
+        const url =
+          typeof input === 'string' ? input : input instanceof Request ? input.url : input.href
+        if (!url.startsWith(subscription.destination.url)) return realFetch(input, init)
+        calls.push({
+          body: typeof init?.body === 'string' ? init.body : '',
+          headers: new Headers(init?.headers),
+          url,
+        })
+        return new Response(null, { status: 200 })
+      })
+
+      const result = await Webhooks.poll({
+        // One row per tick keeps the delivery assertions focused on a single
+        // signed envelope.
+        batchSize: 1,
+        chainId: 42431,
+        eventTypes: ['token:transfer'],
+        headBlockNumber: windowHead,
+        client,
+        store,
+        tidx: realTidx,
+      })
+
+      expect(result.dispatched).toBe(1)
+      expect(calls).toHaveLength(1)
+      expect(calls[0]?.url).toBe(subscription.destination.url)
+
+      // The captured body verifies against the subscription's signing secret.
+      expect(
+        Core.verify({
+          body: calls[0]?.body ?? '',
+          secret: subscription.secret,
+          signature: calls[0]?.headers.get('tempo-signature') ?? '',
+        }),
+      ).toBe(true)
+
+      // The delivered envelope carries the matched transfer row and its type.
+      const envelope = JSON.parse(calls[0]?.body ?? '{}') as Core.Envelope
+      expect(envelope.type).toBe('token:transfer')
+      expect(calls[0]?.headers.get('tempo-event-type')).toBe('token:transfer')
+      expect((envelope.data as { blockNumber: number }).blockNumber).toBe(windowTo)
+
+      // Success resets the failure counter, stamps lastDeliveryAt, stays active.
+      const after = await Core.getSubscription(store, subscription.owner, subscription.id)
+      expect(after?.status).toBe('active')
+      expect(after?.failureCount).toBe(0)
+      expect(after?.lastDeliveryAt).toBeDefined()
+    })
+
+    test('pauses on a failed delivery and re-delivers on the next tick', async () => {
+      const store = Store.memory()
+      const subscription = await createTransferSubscription(store)
+      await Core.setCursor(store, subscription.id, windowCursor)
+
+      const realFetch = globalThis.fetch.bind(globalThis)
+      let attempts = 0
+      vi.spyOn(globalThis, 'fetch').mockImplementation(async (input, init) => {
+        const url =
+          typeof input === 'string' ? input : input instanceof Request ? input.url : input.href
+        if (!url.startsWith(subscription.destination.url)) return realFetch(input, init)
+        attempts++
+        return new Response(null, { status: attempts === 1 ? 500 : 200 })
+      })
+
+      const tick = () =>
+        Webhooks.poll({
+          batchSize: 1,
+          chainId: 42431,
+          eventTypes: ['token:transfer'],
+          headBlockNumber: windowHead,
+          client,
+          store,
+          tidx: realTidx,
+        })
+
+      const first = await tick()
+      expect(first.failed).toBe(1)
+      expect(first.dispatched).toBe(0)
+      // Cursor paused at the prior position so the row re-delivers next tick.
+      expect(decodeCursor(await Core.getCursor(store, subscription.id))).toEqual([
+        windowFrom - 1,
+        endOfBlockIndex,
+      ])
+
+      const second = await tick()
+      expect(second.dispatched).toBe(1)
+      expect(attempts).toBe(2)
+      // Now advanced past the redelivered row (the first row in block 1000002).
+      expect(decodeCursor(await Core.getCursor(store, subscription.id))).toEqual([windowTo, 0])
+    })
+
+    test('auto-disables a subscription after sustained failures', async () => {
+      const store = Store.memory()
+      const subscription = await createTransferSubscription(store)
+      await Core.setCursor(store, subscription.id, windowCursor)
+
+      // Real TIDX queries pass through; only the webhook delivery fails (500).
+      const realFetch = globalThis.fetch.bind(globalThis)
+      vi.spyOn(globalThis, 'fetch').mockImplementation(async (input, init) => {
+        const url =
+          typeof input === 'string' ? input : input instanceof Request ? input.url : input.href
+        if (!url.startsWith(subscription.destination.url)) return realFetch(input, init)
+        return new Response(null, { status: 500 })
+      })
+
+      const tick = () =>
+        Webhooks.poll({
+          batchSize: 1,
+          chainId: 42431,
+          eventTypes: ['token:transfer'],
+          headBlockNumber: windowHead,
+          client,
+          store,
+          tidx: realTidx,
+        })
+
+      // Each tick delivers once and fails; after `maxFailures` ticks the
+      // subscription auto-disables and drops out of the poller's active index.
+      for (let i = 0; i < Core.maxFailures; i++) await tick()
+
+      const disabled = await Core.getSubscription(store, subscription.owner, subscription.id)
+      expect(disabled?.status).toBe('disabled')
+      expect(disabled?.failureCount).toBe(Core.maxFailures)
+
+      // A subsequent tick visits no active subscriptions.
+      const after = await tick()
+      expect(after.subscriptions).toBe(0)
+    })
+  })
+
+  // Full loop through the public HTTP surface: create over the route, let the
+  // poller detect a seeded TIDX row and deliver via the default transport, then
+  // read the recorded outcome back through the deliveries route. Unlike the
+  // `poll` tests above (which seed subscriptions via the core helper), this
+  // proves the route-issued secret and id line up with what is delivered/logged.
+  describe('end-to-end (routes + poller)', () => {
+    test('create → poll → signed delivery → deliveries route records success', async () => {
+      const store = Store.memory()
+      const app = TestApp.client({
+        auth: { source: TestApp.source({ keys: [writer] }) },
+        webhook: { store },
+      })
+
+      // 1. Create through the route; capture the one-time signing secret + id.
+      // The `windowSender` filter pins the scan to the deterministic window rows.
+      const created = await app.v1.webhooks.$post(
+        { json: { ...validBody, chainId: 42431, filters: { sender: windowSender } } },
+        as(writer),
+      )
+      expect(created.status).toBe(200)
+      const { id, secret } = await TestApp.json(created, Webhooks.schema.createWebhook.Response)
+
+      // Anchor the cursor just below the window so the poller scans this tick (a
+      // brand-new subscription anchors at the confirmed head and skips its first
+      // tick).
+      await Core.setCursor(store, id, windowCursor)
+
+      // 2. A local delivery sink that captures the request and acks 200, injected
+      // via `deliverAndRecord`'s `fetch` option (the SSRF guard blocks loopback,
+      // so a real local server can't be a subscriber URL) — no global mock.
+      const calls: { body: string; headers: Headers; url: string }[] = []
+      const fetch = (async (input, init) => {
+        calls.push({
+          body: typeof init?.body === 'string' ? init.body : '',
+          headers: new Headers(init?.headers),
+          url: typeof input === 'string' ? input : '',
+        })
+        return new Response(null, { status: 200 })
+      }) satisfies typeof globalThis.fetch
+
+      // 3. Poll a real TIDX transfer row; dispatch through the real
+      // sign+deliver+record core with the injected transport. `batchSize: 1`
+      // delivers exactly one envelope from the window.
+      const result = await Webhooks.poll({
+        batchSize: 1,
+        chainId: 42431,
+        dispatch: ({ envelope, subscription }) =>
+          Core.deliverAndRecord(store, subscription, envelope, { fetch }),
+        eventTypes: ['token:transfer'],
+        headBlockNumber: windowHead,
+        client,
+        store,
+        tidx: realTidx,
+      })
+      expect(result.dispatched).toBe(1)
+
+      // The subscriber received exactly one POST to its URL, signed verifiably
+      // with the secret the route returned.
+      expect(calls).toHaveLength(1)
+      expect(calls[0]?.url).toBe(validBody.destination.url)
+      expect(
+        Core.verify({
+          body: calls[0]?.body ?? '',
+          secret,
+          signature: calls[0]?.headers.get('tempo-signature') ?? '',
+        }),
+      ).toBe(true)
+      const envelope = JSON.parse(calls[0]?.body ?? '{}') as Core.Envelope
+      expect(envelope.type).toBe('token:transfer')
+
+      // 4. The deliveries route shows the recorded success for this event.
+      const deliveries = await app.v1.webhooks[':id{wh_[A-Za-z0-9_-]+}'].deliveries.$get(
+        { param: { id }, query: {} },
+        as(writer),
+      )
+      const log = await TestApp.json(deliveries, Webhooks.schema.listWebhookDeliveries.Response)
+      expect(log.data).toHaveLength(1)
+      expect(log.data[0]?.status).toBe('succeeded')
+      expect(log.data[0]?.eventId).toBe(envelope.id)
+    })
+  })
+})
+
+describe('matchesOperator', () => {
+  const addr = '0x20c0000000000000000000008f5425160ebe5525'
+  const addr2 = '0x1111111111111111111111111111111111111111'
+
+  test('bare value matches case-insensitively (string kind)', () => {
+    expect(Webhooks.matchesOperator(addr.toUpperCase(), addr)).toBe(true)
+    expect(Webhooks.matchesOperator(addr2, addr)).toBe(false)
+  })
+
+  test('a missing value never matches (fail-closed)', () => {
+    expect(Webhooks.matchesOperator(undefined, addr)).toBe(false)
+  })
+
+  test('{ eq } matches equality', () => {
+    expect(Webhooks.matchesOperator(addr, { eq: addr })).toBe(true)
+  })
+
+  test('{ in } matches membership', () => {
+    expect(Webhooks.matchesOperator(addr, { in: [addr2, addr] })).toBe(true)
+    expect(Webhooks.matchesOperator(addr, { in: [addr2] })).toBe(false)
+  })
+
+  test('{ not } matches inequality', () => {
+    expect(Webhooks.matchesOperator(addr, { not: addr2 })).toBe(true)
+    expect(Webhooks.matchesOperator(addr, { not: addr })).toBe(false)
+  })
+
+  test('compare bare value matches numeric equality', () => {
+    expect(Webhooks.matchesOperator('0x1a', '0x1a', 'number')).toBe(true)
+    expect(Webhooks.matchesOperator('0x1b', '0x1a', 'number')).toBe(false)
+  })
+
+  test('compare range AND-combines bounds', () => {
+    const op = { gte: '0x1', lte: '0x100' }
+    expect(Webhooks.matchesOperator('0x80', op, 'number')).toBe(true)
+    expect(Webhooks.matchesOperator('0x200', op, 'number')).toBe(false)
+  })
+
+  test('bytes selector matches the first four bytes', () => {
+    expect(Webhooks.matchesOperator('0xa9059cbbdeadbeef', { selector: '0xa9059cbb' })).toBe(true)
+    expect(Webhooks.matchesOperator('0x12345678deadbeef', { selector: '0xa9059cbb' })).toBe(false)
+  })
+
+  test('bytes startsWith matches a hex prefix', () => {
+    expect(Webhooks.matchesOperator('0xa9059cbbdeadbeef', { startsWith: '0xa9059cbb' })).toBe(true)
+    expect(Webhooks.matchesOperator('0xdead', { startsWith: '0xa9059cbb' })).toBe(false)
+  })
+})
+
+describe('parseFilters', () => {
+  test('returns validated filters for a known event type', () => {
+    expect(
+      Webhooks.parseFilters('token:transfer', {
+        sender: '0x20c0000000000000000000008f5425160ebe5525',
+      }),
+    ).toMatchInlineSnapshot(`
+      {
+        "sender": "0x20c0000000000000000000008f5425160ebe5525",
+      }
+    `)
+  })
+
+  test('treats undefined filters as the empty (match-all) set', () => {
+    expect(Webhooks.parseFilters('token:transfer', undefined)).toMatchInlineSnapshot(`{}`)
+  })
+
+  test('fails closed on an invalid filter shape', () => {
+    let error: unknown
+    try {
+      Webhooks.parseFilters('token:transfer', { sender: 'not-an-address' })
+    } catch (cause) {
+      error = cause
+    }
+    expect(error).toBeInstanceOf(Core.InvalidFilterError)
+    expect((error as Core.InvalidFilterError).eventType).toBe('token:transfer')
+    expect((error as Core.InvalidFilterError).details.length).toBeGreaterThan(0)
+  })
+})