tapimo 0.10.1 → 0.11.0

package/src/internal/Webhooks.ts

@@ -49,6 +49,16 @@ export type Owner =
       type: 'mpp'
     }
 
+/** API-key scope applied when managing private-resource subscriptions. */
+export type Access = {
+  /** API-key environment. */
+  environment: 'production' | 'sandbox'
+  /** Project attribution, when the key is project-scoped. */
+  projectId?: string | undefined
+  /** API-key scopes used to authorize private resource reads. */
+  scopes: readonly string[]
+}
+
 /**
  * Optional human context describing what a subscription is for. Carried onto
  * every delivered {@link Envelope} and surfaced by destinations (Slack header +
@@ -73,6 +83,8 @@ export type Subscription = {
   createdAt: string
   /** Where matched events are delivered (URL or Slack channel). */
   destination: WebhookDestination.Destination
+  /** API-key environment captured when the subscription was created. */
+  environment?: 'production' | 'sandbox' | undefined
   /** Event type the subscription listens to. */
   eventType: EventType
   /** ISO expiry timestamp; set for MPP-owned subscriptions (TTL-bounded). */
@@ -87,6 +99,8 @@ export type Subscription = {
   lastDeliveryAt?: string | undefined
   /** Authenticated owner. */
   owner: Owner
+  /** Project attribution captured from the creating API key. */
+  projectId?: string | undefined
   /** HMAC signing secret. Returned once at creation; never exposed by reads. */
   secret: string
   /** Lifecycle status. */
@@ -103,12 +117,16 @@ export type CreateInput = {
   context?: Context | undefined
   /** Where matched events are delivered. `url` destinations are SSRF-validated. */
   destination: WebhookDestination.Destination
+  /** API-key environment used to isolate private resource events. */
+  environment?: 'production' | 'sandbox' | undefined
   /** Event type to listen to. */
   eventType: EventType
   /** Event-type-specific filter predicates. */
   filters?: Record<string, unknown> | undefined
   /** Owner derived from the request principal. */
   owner: Owner
+  /** Project attribution used to isolate private resource events. */
+  projectId?: string | undefined
   /** Time-to-live in milliseconds; set the subscription to expire (MPP TTL). */
   ttl?: number | undefined
 }
@@ -181,7 +199,7 @@ export async function createSubscription(
   const now = (options.now ?? (() => new Date()))()
   const iso = now.toISOString()
   // A one-field checkpoint records the live creation head without claiming it
-  // was scanned. The poller expands it using its confirmation depth.
+  // was scanned; it anchors the fanout boundary for the new subscription.
   const pollerCursor =
     options.startBlockNumber === undefined ? undefined : Cursor.encode([options.startBlockNumber])
 
@@ -190,11 +208,13 @@ export async function createSubscription(
     ...(input.context === undefined ? {} : { context: input.context }),
     createdAt: iso,
     destination: input.destination,
+    ...(input.environment === undefined ? {} : { environment: input.environment }),
     eventType: input.eventType,
     failureCount: 0,
     filters: input.filters ?? {},
     id: generateId(now),
     owner: input.owner,
+    ...(input.projectId === undefined ? {} : { projectId: input.projectId }),
     secret: generateSecret(),
     status: 'active',
     updatedAt: iso,
@@ -236,8 +256,14 @@ export async function getSubscription(
   db: Db.Db,
   owner: Owner,
   id: string,
+  options: getSubscription.Options = {},
 ): Promise<Subscription | null> {
-  return WebhookSubscriptions.get(db, owner, id, new Date().toISOString())
+  return WebhookSubscriptions.get(db, owner, id, new Date().toISOString(), options.access)
+}
+
+export declare namespace getSubscription {
+  /** Private-resource visibility options. */
+  type Options = { access?: Access | undefined }
 }
 
 /**
@@ -255,6 +281,8 @@ export async function listSubscriptions(
 export declare namespace listSubscriptions {
   /** Options for {@link listSubscriptions}. */
   type Options = {
+    /** Private-resource visibility scope. */
+    access?: Access | undefined
     /** Return subscriptions older than this id (keyset paging, newest first). */
     cursor?: string | undefined
     /** Maximum subscriptions to return. */
@@ -269,13 +297,22 @@ export declare namespace listSubscriptions {
  * since the per-owner set is bounded by `maxPerOwner`. Feeds the opt-in
  * `meta.totalCount` on `GET /webhooks`.
  */
-export async function countSubscriptions(db: Db.Db, owner: Owner): Promise<number> {
-  return WebhookSubscriptions.count(db, owner, new Date().toISOString())
+export async function countSubscriptions(
+  db: Db.Db,
+  owner: Owner,
+  options: countSubscriptions.Options = {},
+): Promise<number> {
+  return WebhookSubscriptions.count(db, owner, new Date().toISOString(), options.access)
+}
+
+export declare namespace countSubscriptions {
+  /** Private-resource visibility options. */
+  type Options = { access?: Access | undefined }
 }
 
 /**
  * Patches an owner's subscription, re-validating the URL when changed.
- * Returns null when absent. The status column drives the poller's partial
+ * Returns null when absent. The status column drives the partial active
  * index, so no secondary-index maintenance is needed.
  */
 export async function updateSubscription(
@@ -285,7 +322,12 @@ export async function updateSubscription(
   patch: PatchInput,
   options: updateSubscription.Options = {},
 ): Promise<Subscription | null> {
-  const current = await getSubscription(db, owner, id)
+  const current = await getSubscription(
+    db,
+    owner,
+    id,
+    options.access === undefined ? {} : { access: options.access },
+  )
   if (!current) return null
 
   if (current.destination.type !== 'url' && patch.destination?.type === 'url')
@@ -307,43 +349,29 @@ export async function updateSubscription(
 export declare namespace updateSubscription {
   /** Options for {@link updateSubscription}. */
   type Options = {
+    /** Private-resource visibility scope. */
+    access?: Access | undefined
     /** Clock used for timestamps (injectable for tests). */
     now?: (() => Date) | undefined
   }
 }
 
 /** Deletes an owner's subscription; its delivery rows cascade via the FK. */
-export async function deleteSubscription(db: Db.Db, owner: Owner, id: string): Promise<boolean> {
-  return WebhookSubscriptions.remove(db, owner, id, new Date().toISOString())
-}
-
-/**
- * Lists active subscriptions for a `(chainId, eventType)` stream. Used by the
- * poller; one indexed query (the partial status index replaces the old
- * secondary key space).
- */
-export async function listActive(
+export async function deleteSubscription(
   db: Db.Db,
-  chainId: number,
-  eventType: EventType,
-): Promise<Subscription[]> {
-  const pairs = await listActiveWithCursors(db, chainId, eventType)
-  return pairs.map((pair) => pair.subscription)
+  owner: Owner,
+  id: string,
+  options: deleteSubscription.Options = {},
+): Promise<boolean> {
+  return WebhookSubscriptions.remove(db, owner, id, new Date().toISOString(), options.access)
 }
 
-/**
- * Lists a stream's live active subscriptions paired with their poller cursors,
- * from one query. The poller's per-tick lookup.
- */
-export async function listActiveWithCursors(
-  db: Db.Db,
-  chainId: number,
-  eventType: EventType,
-): Promise<{ cursor: string | null; subscription: Subscription }[]> {
-  return WebhookSubscriptions.listActive(db, chainId, eventType, new Date().toISOString())
+export declare namespace deleteSubscription {
+  /** Private-resource visibility options. */
+  type Options = { access?: Access | undefined }
 }
 
-/** Reads every live active subscription on a chain in one poller query. */
+/** Reads every live active subscription on a chain in one query. */
 export async function listActiveForChain(
   db: Db.Db,
   options: listActiveForChain.Options,
@@ -356,28 +384,16 @@ export async function listActiveForChain(
 }
 
 export declare namespace listActiveForChain {
-  /** Filters for the poller's chain-level subscription read. */
+  /** Filters for the chain-level subscription read. */
   type Options = Pick<WebhookSubscriptions.listActiveForChain.Options, 'chainId' | 'eventTypes'>
 }
 
-/**
- * Reads the freshest cursor block across a chain's active subscriptions, or
- * null when none carry a cursor. Creation checkpoints count at their recorded
- * head, so a brand-new subscription reads as fresh.
- */
-export async function maxCursorBlock(db: Db.Db, chainId: number): Promise<number | null> {
-  const cursors = await WebhookSubscriptions.listActiveCursors(
-    db,
-    chainId,
-    new Date().toISOString(),
-  )
-  let max: number | null = null
-  for (const cursor of cursors) {
-    const decoded = Cursor.decode(cursor, ['int', 'int']) ?? Cursor.decode(cursor, ['int'])
-    const block = decoded?.[0]
-    if (typeof block === 'number' && (max === null || block > max)) max = block
-  }
-  return max
+/** Decodes the block component of a subscription cursor, if any. */
+export function cursorBlock(cursor: string | null): number | undefined {
+  if (cursor === null) return undefined
+  const decoded = Cursor.decode(cursor, ['int', 'int']) ?? Cursor.decode(cursor, ['int'])
+  const block = decoded?.[0]
+  return typeof block === 'number' ? block : undefined
 }
 
 /** Reads a subscription's keyset cursor. Returns null when unset. */
@@ -385,41 +401,10 @@ export async function getCursor(db: Db.Db, subscriptionId: string): Promise<stri
   return WebhookSubscriptions.getCursor(db, subscriptionId)
 }
 
-/** Writes a cursor only when its stored value matches the expected cursor. */
-export async function compareAndSetCursor(
-  db: Db.Db,
-  options: compareAndSetCursor.Options,
-): Promise<boolean> {
-  return WebhookSubscriptions.compareAndSetCursor(db, options)
-}
-
-export declare namespace compareAndSetCursor {
-  /** Options for {@link compareAndSetCursor}. */
-  type Options = WebhookSubscriptions.compareAndSetCursor.Options
-}
-
-/** Writes cursors whose stored values match their expected cursors. */
-export async function compareAndSetCursors(
-  db: Db.Db,
-  options: compareAndSetCursors.Options,
-): Promise<Set<string>> {
-  return WebhookSubscriptions.compareAndSetCursors(db, options)
-}
-
-export declare namespace compareAndSetCursors {
-  /** Options for {@link compareAndSetCursors}. */
-  type Options = WebhookSubscriptions.compareAndSetCursors.Options
-}
-
-/** Writes a subscription's keyset cursor. */
-export async function setCursor(db: Db.Db, subscriptionId: string, cursor: string): Promise<void> {
-  await WebhookSubscriptions.setCursor(db, subscriptionId, cursor)
-}
-
 /**
  * Deletes expired MPP-owned subscriptions (delivery rows cascade) and
- * deliveries past retention. Reads already filter expiry at query time — this
- * is the janitor reclaiming space, called best-effort per poller tick.
+ * deliveries past retention. Reads already filter expiry at query time; this
+ * is the janitor reclaiming space, run best-effort on a schedule.
  */
 export async function pruneExpired(db: Db.Db, options: pruneExpired.Options = {}): Promise<void> {
   const iso = (options.now ?? (() => new Date()))().toISOString()
@@ -483,6 +468,10 @@ export async function ensureQueueEvents(
 ): Promise<ensureQueueEvents.Result> {
   const now = (options.now ?? (() => new Date()))()
   const expiresAt = new Date(now.getTime() + (options.ttl ?? deliveryRetentionMs)).toISOString()
+  // Carried so the delivery worker can measure observation-to-attempt without
+  // re-reading the block; replays have no observation and stay null.
+  const observedAt =
+    options.observedAt === undefined ? null : new Date(options.observedAt).toISOString()
   const events = dispatchables.map(({ envelope, subscription }) => ({
     createdAt: now.toISOString(),
     envelope,
@@ -492,6 +481,7 @@ export async function ensureQueueEvents(
     expiresAt,
     // Due immediately; the value orders the sweep so it is never null here.
     nextAttemptAt: now.toISOString(),
+    observedAt,
     subscriptionId: subscription.id,
   }))
   return {
@@ -513,6 +503,8 @@ export declare namespace ensureQueueEvents {
   type Options = {
     /** Clock used for staging timestamps. */
     now?: (() => Date) | undefined
+    /** Epoch ms the head owing these events was observed; absent on replays. */
+    observedAt?: number | undefined
     /** Staged-envelope TTL in ms; defaults to {@link deliveryRetentionMs}. */
     ttl?: number | undefined
   }
@@ -645,10 +637,13 @@ export async function deliverClaimedAndRecord(
     new Date().toISOString(),
   )
   if (!subscription || subscription.status !== 'active') return { status: 'skipped' }
+  // A staged row predating the observation column, or a replay, reads null.
+  const observedAt = claimed.observedAt ? Date.parse(claimed.observedAt) : Number.NaN
   return {
     result: await deliverAndRecord(db, subscription, claimed.envelope, {
       ...options,
       dequeuedAt,
+      ...(Number.isNaN(observedAt) ? {} : { observedAt }),
       subscriptionReadMs: Date.now() - subscriptionReadStartedAt,
     }),
     status: 'delivered',
@@ -660,6 +655,8 @@ export declare namespace deliverClaimedAndRecord {
   type Claimed = {
     /** Immutable event envelope to deliver. */
     envelope: Envelope
+    /** ISO head-observation stamp carried by the staged row; null on replays. */
+    observedAt?: string | null | undefined
     /** Subscription re-resolved for current status and secret. */
     subscriptionId: string
   }
@@ -707,7 +704,7 @@ export async function recordDelivery(
 ): Promise<void> {
   const ttl = options.ttl ?? deliveryRetentionMs
   // The retention deadline replaces the old store TTL: reads filter on it at
-  // query time and the poller prunes past it. Anchored to write time (not the
+  // query time and pruning reclaims past it. Anchored to write time (not the
   // row's `createdAt`, which tests pin) — exactly like the old `put` TTL.
   const expiresAt = new Date(Date.now() + ttl).toISOString()
   await WebhookDeliveries.insert(db, delivery, expiresAt)
@@ -765,7 +762,7 @@ export async function getDelivery(
 
 /**
  * Default number of consecutive delivery failures after which a subscription
- * auto-disables (and is dropped from the poller's active index).
+ * auto-disables (and is dropped from the partial active index).
  */
 export const maxFailures = 10
 
@@ -798,7 +795,7 @@ export declare namespace recordSuccess {
 /**
  * Records a failed delivery: atomically increments the consecutive-failure
  * counter and, once it reaches `maxFailures`, sets `status: 'disabled'` so the
- * subscription drops out of the poller's partial index (surfaced via the API).
+ * subscription drops out of the partial active index (surfaced via the API).
  * Returns the updated subscription.
  */
 export async function recordFailure(
@@ -861,23 +858,32 @@ export async function deliverAndRecord(
       return { error: 'delivery failed before request', ok: false }
     }
   })()
-  const stateWriteStartedAt = Date.now()
-  if (result.ok) await recordSuccess(db, subscription, options)
-  else await recordFailure(db, subscription, options)
-  const stateWriteMs = Date.now() - stateWriteStartedAt
-
+  // Overlapped: the two writes touch different rows and the log carries the
+  // immutable pre-attempt subscription, so it never reads the state write's
+  // result. Sequentially they cost two Postgres round trips per delivery.
+  const writeStartedAt = Date.now()
   // Append a delivery-log row. Best-effort: a logging failure must never change
   // the delivery outcome the caller (Queue consumer / inline path) acts on.
-  const deliveryLogStartedAt = Date.now()
-  try {
-    await recordDelivery(
-      db,
-      buildDelivery({ attempt, envelope, result, subscription }, options),
-      options.deliveryRetentionMs === undefined ? {} : { ttl: options.deliveryRetentionMs },
-    )
-  } catch {
-    // delivery logging is best-effort
-  }
+  const deliveryLog = (async () => {
+    try {
+      await recordDelivery(
+        db,
+        buildDelivery({ attempt, envelope, result, subscription }, options),
+        options.deliveryRetentionMs === undefined ? {} : { ttl: options.deliveryRetentionMs },
+      )
+    } catch {
+      // delivery logging is best-effort
+    }
+    return Date.now() - writeStartedAt
+  })()
+  const stateWrite = (async () => {
+    if (result.ok) await recordSuccess(db, subscription, options)
+    else await recordFailure(db, subscription, options)
+    return Date.now() - writeStartedAt
+  })()
+  // A state-write rejection still propagates to the caller's retry path; the
+  // log promise never rejects, so it cannot mask it or go unhandled.
+  const [stateWriteMs, deliveryLogMs] = await Promise.all([stateWrite, deliveryLog])
   const completedAt = Date.now()
 
   // Emit after all delivery work so the timings cover every stage. The
@@ -894,19 +900,34 @@ export async function deliverAndRecord(
       subscription,
       attempt,
       timings: {
-        deliveryLogMs: completedAt - deliveryLogStartedAt,
+        deliveryLogMs,
         envelopeToQueueMs:
           options.queuedAt === undefined || Number.isNaN(envelopeAt)
             ? undefined
             : Math.max(0, options.queuedAt - envelopeAt),
         endToEndMs: eventAt === undefined ? undefined : Math.max(0, completedAt - eventAt),
+        // The attempt leaving, not bookkeeping finishing: everything after
+        // `startedAt` is either the subscriber's time or our own recording,
+        // neither of which delays the event reaching them. Gated on a request
+        // actually being made, so a failure before send (formatting, invalid
+        // destination) does not report an attempt that never left.
+        eventToAttemptMs:
+          eventAt === undefined || result.durationMs === undefined
+            ? undefined
+            : Math.max(0, startedAt - eventAt),
         eventToEnvelopeMs:
           eventAt === undefined || Number.isNaN(envelopeAt)
             ? undefined
             : Math.max(0, envelopeAt - eventAt),
+        observedToAttemptMs:
+          options.observedAt === undefined || result.durationMs === undefined
+            ? undefined
+            : Math.max(0, startedAt - options.observedAt),
+        preflightMs: Math.max(0, startedAt - dequeuedAt),
         processingMs: Math.max(0, completedAt - dequeuedAt),
         queueWaitMs:
           options.queuedAt === undefined ? undefined : Math.max(0, dequeuedAt - options.queuedAt),
+        settleMs: Math.max(0, completedAt - writeStartedAt),
         stateWriteMs,
         subscriptionReadMs: options.subscriptionReadMs,
       },
@@ -953,6 +974,8 @@ export declare namespace deliverAndRecord {
     metrics?: Metrics.Metrics | undefined
     /** Clock used for timestamps; injectable for tests. */
     now?: (() => Date) | undefined
+    /** Epoch ms the head owing this event was observed; absent on replays. */
+    observedAt?: number | undefined
     /** Cloudflare Queue delivery attempt, starting at one; absent for inline delivery paths. */
     queueAttempt?: number | undefined
     /** Queue enqueue time as epoch milliseconds, used to isolate queue wait. */
@@ -1037,8 +1060,11 @@ function buildDelivery(
  * re-deliveries are dedupable by the receiver.
  */
 export function eventId(options: eventId.Options): string {
-  const input = `${options.chainId}:${options.eventType}:${options.blockNumber}:${options.logIndex}`
-  return `evt_${Hash.sha256(Hex.fromString(input)).slice(2)}`
+  return eventIdFromKey({
+    chainId: options.chainId,
+    eventType: options.eventType,
+    key: `${options.blockNumber}:${options.logIndex}`,
+  })
 }
 
 export declare namespace eventId {
@@ -1055,6 +1081,24 @@ export declare namespace eventId {
   }
 }
 
+/** Computes a stable event id from an event-type-specific identity key. */
+export function eventIdFromKey(options: eventIdFromKey.Options): string {
+  const input = `${options.chainId}:${options.eventType}:${options.key}`
+  return `evt_${Hash.sha256(Hex.fromString(input)).slice(2)}`
+}
+
+export declare namespace eventIdFromKey {
+  /** Stable identity inputs for a webhook event. */
+  type Options = {
+    /** Chain the event belongs to. */
+    chainId: number
+    /** Event type. */
+    eventType: EventType
+    /** Stable event-type-specific identity. */
+    key: string
+  }
+}
+
 /** The JSON envelope delivered to subscribers. */
 export type Envelope = {
   /** Chain the event occurred on. */
@@ -1108,6 +1152,38 @@ export declare namespace buildEnvelope {
   }
 }
 
+/** Builds a delivery envelope from a stable application-event identity. */
+export function buildKeyedEnvelope(options: buildKeyedEnvelope.Options): Envelope {
+  const { subscription } = options
+  return {
+    chainId: subscription.chainId,
+    ...(subscription.context === undefined ? {} : { context: subscription.context }),
+    createdAt: (options.createdAt ?? new Date()).toISOString(),
+    data: options.data,
+    id: eventIdFromKey({
+      chainId: subscription.chainId,
+      eventType: subscription.eventType,
+      key: options.key,
+    }),
+    subscriptionId: subscription.id,
+    type: subscription.eventType,
+  }
+}
+
+export declare namespace buildKeyedEnvelope {
+  /** Application-event envelope fields. */
+  type Options = {
+    /** Timestamp to stamp on the envelope; defaults to now. */
+    createdAt?: Date | undefined
+    /** Public event payload. */
+    data: unknown
+    /** Stable event-type-specific identity. */
+    key: string
+    /** Subscription the event matched. */
+    subscription: Subscription
+  }
+}
+
 /**
  * Builds a synthetic `ping` envelope so an owner can test a subscription's
  * endpoint (connectivity, TLS, signature verification) without waiting for a real

package/src/internal/funding/DepositWebhook.test.ts

@@ -0,0 +1,131 @@
+import * as TestApp from '../../../test/App.js'
+import * as TestFunding from '../../../test/Funding.js'
+import * as WebhookQueueEvents from '../../db/tables/webhookQueueEvents.js'
+import * as Webhooks from '../Webhooks.js'
+import * as Deposit from './Deposit.js'
+import * as FundingDepositAddress from './DepositAddress.js'
+import * as DepositWebhook from './DepositWebhook.js'
+
+const db = TestApp.database()
+
+describe('stage', () => {
+  test('matches owner, environment, project, and filters with stable event ids', async () => {
+    const orgId = 'org_funding_deposit_webhook'
+    const projectId = 'prj_funding_deposit_webhook'
+    const address = await FundingDepositAddress.create(db, {
+      apiKeyId: 'key_funding_deposit_webhook',
+      deliveryStrategy: 'provider',
+      environment: 'production',
+      now: new Date('2026-08-12T00:00:00.000Z'),
+      orgId,
+      projectId,
+      providerOutputToken: TestFunding.providerOutputToken(),
+      snapshot: TestFunding.depositAddressSnapshot({
+        address: 'TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE',
+        recipient: `0x${'ab'.repeat(20)}`,
+      }),
+    })
+    const deposit = await Deposit.create(db, {
+      now: new Date('2026-08-12T00:01:00.000Z'),
+      providerRequestId: 'relay_deposit_webhook',
+      snapshot: TestFunding.depositSnapshot(address.id),
+      sourceTransactionHash: `0x${'aa'.repeat(32)}`,
+      sourceTransferIndex: 0,
+    })
+    const completed = await Deposit.transition(db, {
+      expectedVersion: deposit.version,
+      id: deposit.id,
+      status: 'completed',
+    })
+    if (completed.type !== 'applied') throw new Error('Expected deposit transition to apply.')
+
+    const filters = {
+      depositAddressId: address.id,
+      recipient: address.recipient.toLowerCase(),
+      status: 'completed',
+    }
+    const org = await subscription({ filters, orgId })
+    const project = await subscription({ filters, orgId, projectId })
+    await subscription({ orgId, projectId: 'prj_funding_deposit_sibling' })
+    await subscription({ environment: 'sandbox', orgId })
+    await subscription({ filters: { status: 'refunded' }, orgId })
+
+    const first = await DepositWebhook.stage(db, { records: [completed.record] })
+    const second = await DepositWebhook.stage(db, { records: [completed.record] })
+    expect({ created: first.created, repeated: second.created }).toEqual({
+      created: 2,
+      repeated: 0,
+    })
+    expect(first.references.map((reference) => reference.subscriptionId)).toEqual([
+      org.id,
+      project.id,
+    ])
+    const event = await WebhookQueueEvents.get(db, first.references[0]!)
+    expect(event?.envelope).toMatchObject({
+      chainId: 4217,
+      data: { id: completed.record.id, status: 'completed' },
+      id: first.references[0]!.eventId,
+      subscriptionId: org.id,
+      type: 'funding:deposit.updated',
+    })
+  })
+})
+
+describe('transition', () => {
+  test('commits the deposit version with its webhook obligation', async () => {
+    const orgId = 'org_funding_deposit_transition'
+    const address = await FundingDepositAddress.create(db, {
+      apiKeyId: 'key_funding_deposit_transition',
+      deliveryStrategy: 'provider',
+      environment: 'production',
+      now: new Date('2026-08-12T01:00:00.000Z'),
+      orgId,
+      providerOutputToken: TestFunding.providerOutputToken(),
+      snapshot: TestFunding.depositAddressSnapshot(),
+    })
+    const deposit = await Deposit.create(db, {
+      now: new Date('2026-08-12T01:01:00.000Z'),
+      providerRequestId: 'relay_deposit_transition',
+      snapshot: TestFunding.depositSnapshot(address.id),
+      sourceTransactionHash: `0x${'bb'.repeat(32)}`,
+      sourceTransferIndex: 0,
+    })
+    await subscription({ filters: {}, orgId })
+
+    const transitioned = await DepositWebhook.transition(db, {
+      expectedVersion: deposit.version,
+      id: deposit.id,
+      status: 'bridging',
+    })
+    if (transitioned.result.type !== 'applied') throw new Error('Expected applied transition.')
+
+    expect(transitioned.references).toHaveLength(1)
+    expect(await WebhookQueueEvents.get(db, transitioned.references[0]!)).toMatchObject({
+      envelope: {
+        data: { id: deposit.id, status: 'bridging' },
+        id: transitioned.references[0]!.eventId,
+      },
+    })
+  })
+})
+
+function subscription(options: subscription.Options) {
+  return Webhooks.createSubscription(db, {
+    chainId: 4217,
+    destination: { type: 'url', url: 'https://example.com/webhooks/tempo' },
+    environment: options.environment ?? 'production',
+    eventType: 'funding:deposit.updated',
+    filters: options.filters ?? { recipient: `0x${'ab'.repeat(20)}`, status: 'completed' },
+    owner: { orgId: options.orgId, type: 'api_key' },
+    ...(options.projectId === undefined ? {} : { projectId: options.projectId }),
+  })
+}
+
+declare namespace subscription {
+  type Options = {
+    environment?: 'production' | 'sandbox' | undefined
+    filters?: Record<string, unknown> | undefined
+    orgId: string
+    projectId?: string | undefined
+  }
+}