feat(webhooks): dispatch on emit instead of waiting for the next cron tick (#1256)

* feat(webhooks): dispatch on emit instead of waiting for the next cron tick The webhook dispatcher ran only on a per-minute cron, so the floor on delivery latency was up to 60 seconds plus the request. An external consumer that wanted to react as a transaction landed had only one alternative: polling /api/events, which the 100 rpm per-key limit makes expensive and which still cannot beat the tick interval. Schedules one dispatch cycle as soon as deliveries are enqueued. The cron is unchanged and remains the retry and sweep path; this only moves the first attempt forward. Wired into the event-bus fanout plus the two routes that enqueue a delivery directly: the :test verb, whose entire purpose is telling someone whether their receiver works, and the manual delivery retry. Three properties are load-bearing and covered by tests. The kick is never awaited, because eventBus.emit is awaited at ~99 call sites including journal_entry.committed and each delivery can burn a 10 s receiver timeout. It coalesces per function instance, so a bulk booking that emits once per row does not schedule one claim round trip per row. It claims 5 rows rather than the cron's 50, because it runs on the tail of a user-facing request. Double delivery is not a risk: claim_due_webhook_deliveries already claims FOR UPDATE SKIP LOCKED and flips rows to in_flight in the same statement, so a kick racing the cron sees disjoint rows. Does not close #1201, which asks for a realtime stream for API consumers. This is the cheap half. Refs #1201 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * docs(webhooks): stop claiming the kick makes double delivery impossible Adversarial review of the previous commit caught an overstatement in its own comments. SKIP LOCKED keeps a kick and the cron from claiming the same row at the same moment, but claim_due_webhook_deliveries autocommits before any POST is issued, so from then on ownership is only status='in_flight' and a later cycle's recoverStuckInFlight sweep can re-arm a row still queued behind an earlier cycle's serial loop. Delivery is at-least-once, which is what the public docs already tell receivers ("the same delivery id may arrive more than once ... idempotency is on you"). The comments contradicted that. No behaviour change. The kick does not create this window: the cron claims 50 rows serially against the same 20 s stuck threshold, which is wider than what a batch of 5 can open. Refs #1201 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-07-28 18:08:24 +02:00
parent e171bffa97
commit 49ff234954
9 changed files with 266 additions and 12 deletions
@@ -2,14 +2,15 @@
 * /api/v1/companies/{companyId}/webhooks/{id}/test: POST :test verb.
 *
 * Enqueues a synthetic `webhook.test` delivery against the configured
- * receiver. The dispatcher cron picks it up at next-minute boundary
- * exactly as it would a real event. The response returns the
+ * receiver and kicks a dispatch cycle immediately, exactly as a real event
+ * does (#1201); the cron remains the retry path. The response returns the
 * webhook_delivery_id so the caller can poll
 * GET /webhooks/{id}/deliveries?delivery_id=... to see the outcome.
 */

 import { z } from 'zod'
 import { ok } from '@/lib/api/v1/response'
+import { kickWebhookDispatch } from '@/lib/webhooks/dispatch-kick'
 import { registerEndpoint, dataEnvelope } from '@/lib/api/v1/registry'
 import { withApiV1 } from '@/lib/api/v1/with-api-v1'
 import { v1ErrorResponse, v1ErrorResponseFromCode } from '@/lib/api/v1/errors'
@@ -26,7 +27,7 @@ registerEndpoint({
  path: '/api/v1/companies/:companyId/webhooks/:id/test',
  summary: 'Send a synthetic test event to a webhook.',
  description:
-    'Enqueues a webhook.test delivery against the configured receiver. The dispatcher delivers it on the next per-minute cron tick. Use the returned webhook_delivery_id to poll GET /webhooks/{id}/deliveries for the outcome.',
+    'Enqueues a webhook.test delivery against the configured receiver and dispatches it immediately, so the outcome is normally available within a second or two rather than on the next per-minute cron tick. Use the returned webhook_delivery_id to poll GET /webhooks/{id}/deliveries for the outcome.',
  useWhen:
    'After creating or modifying a webhook, before relying on it in production: to validate that the receiver is reachable and that signature verification works on the receiver side.',
  doNotUseFor:
@@ -111,6 +112,11 @@ export const POST = withApiV1<{ params: Promise<{ companyId: string; id: string
      })
    }

+    // Deliver now rather than on the next cron tick. This verb exists to tell
+    // someone whether their receiver works; making them wait up to a minute
+    // for that answer is the whole complaint in #1201.
+    kickWebhookDispatch()
+
    return ok(
      { webhook_delivery_id: (delivery as { id: string }).id, status: 'pending' as const },
      { requestId: ctx.requestId },
@@ -23,6 +23,7 @@ import { ok } from '@/lib/api/v1/response'
 import { registerEndpoint, dataEnvelope } from '@/lib/api/v1/registry'
 import { withApiV1 } from '@/lib/api/v1/with-api-v1'
 import { v1ErrorResponse, v1ErrorResponseFromCode } from '@/lib/api/v1/errors'
+import { kickWebhookDispatch } from '@/lib/webhooks/dispatch-kick'
 import { minimisePayload } from '@/lib/webhooks/handler'
 import { validateWebhookUrl } from '@/lib/webhooks/url-guard'
 import { hasScope } from '@/lib/auth/api-keys'
@@ -213,6 +214,11 @@ export const POST = withApiV1<{ params: Promise<{ id: string }> }>(
      })
    }

+    // Deliver now rather than on the next cron tick (#1201). A manual retry
+    // is someone watching a failed delivery and asking for it again; the
+    // cron stays the path for the automatic backoff retries.
+    kickWebhookDispatch()
+
    return ok(
      { webhook_delivery_id: (replay as { id: string }).id, status: 'pending' as const },
      { requestId: ctx.requestId },