feat(webhooks): standalone Telegram + HelloSign inbound webhook providers (#104)

* feat(webhooks): add standalone Telegram + HelloSign inbound providers

Both providers had verifier logic at the connector-adapter level but no
standalone WebhookProvider, so the inbound webhook router (and consumers that
drive it — e.g. a per-connection inbound route) could not use them. Add them to
webhooks/providers.ts (auto-exported from /webhooks):

- telegramWebhookProvider: Telegram authenticates webhooks by echoing the
  secret_token set at setWebhook time in the X-Telegram-Bot-Api-Secret-Token
  header (the body is NOT signed), so we constant-time compare it to the
  per-connection secret. update_id is the idempotency anchor; the first present
  update key names the event (telegram.message, telegram.callback_query, ...).
  New capability — the connector only had a setWebhook mutation + a TODO.
- hellosignWebhookProvider: Dropbox Sign has no signature header; the body
  carries event.event_hash = HMAC_SHA256(apiKey, event_time + event_type), so
  `secret` is the account API key. Handles JSON, form-urlencoded `json=`, and
  multipart `name="json"` bodies (mirrors the connector adapter's extraction).

Tests cover verify pass/fail/missing and parse for both (incl. HelloSign's
form-encoded body). Full suite (4077) + typecheck + build green. Additive
exports only: 0.39.0 -> 0.40.0.

* fix(webhooks): harden telegram and hellosign inbound providers

- HelloSign: key providerEventId on a sha256 digest of the parsed body rather than event_hash. event_hash = HMAC(apiKey, event_time + event_type), so two distinct same-type events in the same second collide and the second would be dropped by delivery dedup. The body digest is stable across redeliveries of one event and distinct across events that differ in content.
- Telegram: extend TELEGRAM_UPDATE_KEYS to the full Bot API Update set (business_connection, edited_business_message, deleted_business_messages, message_reaction, message_reaction_count, purchased_paid_media, chat_boost, removed_chat_boost) so those deliveries classify by type instead of telegram.unknown.
- Tests: multipart name="json" verify+parse, same-second collision + redelivery stability, and a message_reaction regression.

typecheck clean; full suite green (4080).

* fix(webhooks): decode form-urlencoded hellosign bodies with URLSearchParams

The `json=` fallback used decodeURIComponent, which does not convert `+` to a space — but application/x-www-form-urlencoded encodes spaces as `+`. Space-bearing fields (e.g. signature_request.title) were corrupted, and JSON with structural whitespace could fail to parse. Switch to URLSearchParams.get('json'), which decodes `+` and percent-escapes correctly. Applied to both the new webhook provider and the HelloSign connector adapter it mirrors.

typecheck clean; full suite green (4081).

* fix(webhooks): make hellosign provider production-correct (ACK body + canonical event id)

- Router: add an optional WebhookProvider.successResponse so a provider can declare the 200 ACK body/headers it needs; WebhookRouter.handle() returns it on a verified delivery instead of the default { received, total } JSON. The frozen status contract is unchanged.
- HelloSign: declare the literal 'Hello API Event Received' ACK (text/plain) Dropbox Sign requires — without it a verified delivery is treated as failed and retried indefinitely.
- HelloSign: prefer the canonical event.event_id for providerEventId, falling back to the body digest only when it is absent (parity with the connector adapter; the digest still avoids the event_hash same-second collision).
- Tests: event_id preference, the ACK field, and a router-level assertion that a verified HelloSign delivery returns 200 with body 'Hello API Event Received'.

typecheck clean; full suite green (4084).

* fix(webhooks): linear multipart json extraction, removing quadratic backtracking

The HelloSign multipart `name="json"` fallback used a regex with two sequential lazy scans (`name="json"[^]*?\r?\n\r?\n([\s\S]*?)\r?\n--`). On a body with many `\r\n\r\n` separators and no closing boundary it backtracks quadratically — measured ~26s for a 400KB body — so a crafted POST to the public webhook ingress could stall the event loop. Replace it with indexOf + fixed-shape separator probes (no `*`/`+` quantifiers), which extract the same part in a single linear pass (~1.5ms at 1MB) with identical semantics. Applied to both the webhook provider and the connector adapter that share the pattern.

typecheck clean; full suite green (4085).

* docs(webhooks): list telegram and hellosign providers in the router table

The package now exports telegramWebhookProvider and hellosignWebhookProvider; add them to the WebhookRouter row of the API reference.

Author: Tjemmmic

README.md

@@ -176,7 +176,7 @@ OAuth credentials.
 | `validateProviderPassthroughRequest` | Policy-gated provider-native HTTP escape hatch validation. |
 | `buildIntegrationToolCatalog` | Converts connector actions into agent/tool definitions. |
 | `discoverWorkspaceCapabilities` | Per-workspace capability discovery: scope-gated, MCP-shape tool descriptors for agent runtime binding. |
-| `WebhookRouter` (+ `stripeWebhookProvider`, `docusealWebhookProvider`, `slackWebhookProvider`, `gmailWebhookProvider`, `gdriveWebhookProvider`, `genericHmacWebhookProvider`) | Inbound webhook router: verify signature, parse, idempotency dedup, async deliver. |
+| `WebhookRouter` (+ `stripeWebhookProvider`, `docusealWebhookProvider`, `slackWebhookProvider`, `gmailWebhookProvider`, `gdriveWebhookProvider`, `telegramWebhookProvider`, `hellosignWebhookProvider`, `genericHmacWebhookProvider`) | Inbound webhook router: verify signature, parse, idempotency dedup, async deliver. |
 | `searchIntegrationTools` | Intent search over normalized integration tools. |
 | `buildDefaultIntegrationRegistry` | Composes setup specs and vendored catalog metadata into one deduplicated connector registry. |
 | `composeIntegrationRegistry` | Merges arbitrary catalog sources with explicit aliases, precedence, support tiers, and conflict diagnostics. |

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-integrations",
-  "version": "0.39.0",
+  "version": "0.40.0",
   "description": "Vendor-neutral integration contracts and runtime helpers for sandbox and agent apps.",
   "homepage": "https://github.com/tangle-network/agent-integrations#readme",
   "repository": {

src/connectors/adapters/hellosign.ts

@@ -648,26 +648,33 @@ function parseInboundBody(rawBody: string): HelloSignInboundBody | null {
   } catch {
     // fall through to form-data extraction
   }
-  // crude multipart extraction: look for a `json=` value (form-urlencoded
-  // fallback some Dropbox Sign apps still emit)
-  const match = /(?:^|&)json=([^&]+)/.exec(rawBody)
-  if (match) {
+  // form-urlencoded `json=` fallback some Dropbox Sign apps still emit.
+  // URLSearchParams decodes `+` as a space (decodeURIComponent leaves it
+  // literal) and resolves percent-escapes, so space-bearing fields survive.
+  const formJson = new URLSearchParams(rawBody).get('json')
+  if (formJson) {
     try {
-      return JSON.parse(decodeURIComponent(match[1])) as HelloSignInboundBody
+      return JSON.parse(formJson) as HelloSignInboundBody
     } catch {
       return null
     }
   }
-  // multipart/form-data with a `name="json"` part
-  const partMatch = /name="json"[^]*?\r?\n\r?\n([\s\S]*?)\r?\n--/m.exec(rawBody)
-  if (partMatch) {
-    try {
-      return JSON.parse(partMatch[1]) as HelloSignInboundBody
-    } catch {
-      return null
-    }
+  // multipart/form-data with a `name="json"` part. Extract linearly (indexOf +
+  // fixed-shape separator probes, no unbounded lazy regex) so a hostile body
+  // can't drive quadratic backtracking on this public ingress.
+  const nameIdx = rawBody.indexOf('name="json"')
+  if (nameIdx === -1) return null
+  const afterName = rawBody.slice(nameIdx)
+  const sep = /\r?\n\r?\n/.exec(afterName)
+  if (!sep) return null
+  const partBody = afterName.slice(sep.index + sep[0].length)
+  const end = /\r?\n--/.exec(partBody)
+  if (!end) return null
+  try {
+    return JSON.parse(partBody.slice(0, end.index)) as HelloSignInboundBody
+  } catch {
+    return null
   }
-  return null
 }
 
 async function ensureFreshAccessToken(

src/webhooks/providers.ts

@@ -18,7 +18,7 @@ import {
   verifyStripeSignature,
 } from '../connectors/webhooks.js'
 import type { WebhookEnvelope, WebhookHeaders, WebhookProvider, SignatureVerification } from './router.js'
-import { createHmac, timingSafeEqual } from 'node:crypto'
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto'
 
 /** Stripe webhook provider. Signature header `Stripe-Signature`. */
 export const stripeWebhookProvider: WebhookProvider = {
@@ -191,6 +191,172 @@ export const gdriveWebhookProvider: WebhookProvider = {
   },
 }
 
+/** The Telegram update keys, in resolution order — the first present key names
+ *  the update kind (`telegram.message`, `telegram.callback_query`, …). */
+const TELEGRAM_UPDATE_KEYS = [
+  'message',
+  'edited_message',
+  'channel_post',
+  'edited_channel_post',
+  'business_connection',
+  'business_message',
+  'edited_business_message',
+  'deleted_business_messages',
+  'message_reaction',
+  'message_reaction_count',
+  'inline_query',
+  'chosen_inline_result',
+  'callback_query',
+  'shipping_query',
+  'pre_checkout_query',
+  'purchased_paid_media',
+  'poll',
+  'poll_answer',
+  'my_chat_member',
+  'chat_member',
+  'chat_join_request',
+  'chat_boost',
+  'removed_chat_boost',
+] as const
+
+/** Telegram Bot API webhook provider. Telegram does NOT sign the body — it
+ *  authenticates by echoing the `secret_token` set at `setWebhook` time in the
+ *  `X-Telegram-Bot-Api-Secret-Token` header. We compare it constant-time to the
+ *  per-connection secret. `update_id` is the idempotency anchor. */
+export const telegramWebhookProvider: WebhookProvider = {
+  id: 'telegram',
+  verifySignature({ headers, secret }): SignatureVerification {
+    const token = firstHeader(headers, 'x-telegram-bot-api-secret-token')
+    if (!token) return { valid: false, reason: 'missing_telegram_secret_token' }
+    const a = Buffer.from(token, 'utf-8')
+    const b = Buffer.from(secret, 'utf-8')
+    if (a.length !== b.length) return { valid: false, reason: 'invalid_secret_token' }
+    return timingSafeEqual(a, b) ? { valid: true } : { valid: false, reason: 'invalid_secret_token' }
+  },
+  parse({ rawBody, headers, now }): WebhookEnvelope[] {
+    const evt = safeJson(rawBody) as ({ update_id?: number } & Record<string, unknown>) | null
+    if (!evt || typeof evt !== 'object') return []
+    const kind = TELEGRAM_UPDATE_KEYS.find((k) => k in evt) ?? 'unknown'
+    return [{
+      provider: 'telegram',
+      eventType: `telegram.${kind}`,
+      providerEventId: typeof evt.update_id === 'number' ? String(evt.update_id) : undefined,
+      receivedAt: now ?? Date.now(),
+      payload: evt,
+      headers: normalizeHeaders(headers),
+    }]
+  },
+}
+
+/** Dropbox Sign (HelloSign) webhook provider. There is NO signature header:
+ *  the body carries `event.event_hash = HMAC_SHA256(apiKey, event_time +
+ *  event_type)` (hex), so the `secret` here is the account's API key (the
+ *  caller resolves it from the connection credential). The body is JSON, or a
+ *  `json=`/multipart `name="json"` form field on older apps. */
+export const hellosignWebhookProvider: WebhookProvider = {
+  id: 'hellosign',
+  // Dropbox Sign acknowledges a delivery only when the response body is exactly
+  // 'Hello API Event Received'; any other body makes it retry the event.
+  successResponse: { body: 'Hello API Event Received', headers: { 'content-type': 'text/plain' } },
+  verifySignature({ rawBody, secret }): SignatureVerification {
+    const body = parseHelloSignBody(rawBody)
+    const event = body?.event
+    if (
+      !event ||
+      typeof event.event_time !== 'string' ||
+      typeof event.event_type !== 'string' ||
+      typeof event.event_hash !== 'string'
+    ) {
+      return { valid: false, reason: 'missing_event_fields' }
+    }
+    const expected = createHmac('sha256', secret)
+      .update(`${event.event_time}${event.event_type}`)
+      .digest('hex')
+    const a = Buffer.from(event.event_hash.toLowerCase(), 'utf-8')
+    const b = Buffer.from(expected.toLowerCase(), 'utf-8')
+    if (a.length !== b.length) return { valid: false, reason: 'invalid_signature' }
+    return timingSafeEqual(a, b) ? { valid: true } : { valid: false, reason: 'invalid_signature' }
+  },
+  parse({ rawBody, headers, now }): WebhookEnvelope[] {
+    const body = parseHelloSignBody(rawBody)
+    const event = body?.event
+    if (!event) return []
+    return [{
+      provider: 'hellosign',
+      eventType: `hellosign.${event.event_type ?? 'unknown'}`,
+      // Prefer Dropbox Sign's canonical `event.event_id` (stable across
+      // redeliveries, correlates with the provider). Fall back to a digest of
+      // the parsed body when it's absent: `event_hash` = HMAC(apiKey,
+      // event_time + event_type), so two distinct same-type events in the same
+      // second share it — the body digest stays distinct across differing
+      // events and identical across redeliveries of one event.
+      providerEventId:
+        typeof event.event_id === 'string' && event.event_id.length > 0
+          ? event.event_id
+          : createHash('sha256').update(JSON.stringify(body)).digest('hex'),
+      receivedAt: now ?? Date.now(),
+      payload: body,
+      headers: normalizeHeaders(headers),
+    }]
+  },
+}
+
+interface HelloSignInboundBody {
+  event?: {
+    event_time?: string
+    event_type?: string
+    event_hash?: string
+    event_id?: string
+  }
+}
+
+/** Dropbox Sign posts JSON, a form-urlencoded `json=` field, or a
+ *  multipart `name="json"` part depending on app vintage. Mirrors the
+ *  connector adapter's body extraction. */
+function parseHelloSignBody(rawBody: string): HelloSignInboundBody | null {
+  try {
+    const json = JSON.parse(rawBody) as HelloSignInboundBody
+    if (json && typeof json === 'object') return json
+  } catch {
+    // fall through to form-data extraction
+  }
+  // application/x-www-form-urlencoded `json=` field. URLSearchParams decodes
+  // `+` as a space (decodeURIComponent leaves it literal) and resolves
+  // percent-escapes, so space-bearing string fields aren't corrupted.
+  const formJson = new URLSearchParams(rawBody).get('json')
+  if (formJson) {
+    try {
+      return JSON.parse(formJson) as HelloSignInboundBody
+    } catch {
+      return null
+    }
+  }
+  // multipart/form-data with a `name="json"` part. Extract linearly (indexOf +
+  // fixed-shape separator probes, no unbounded lazy regex) so a hostile body
+  // can't drive quadratic backtracking on this public ingress.
+  return extractMultipartJsonField(rawBody)
+}
+
+/** Pull the `json` part out of a multipart/form-data body without an
+ *  unbounded backtracking regex. Returns null if the part isn't present or
+ *  isn't valid JSON. The separator probes (`\r?\n\r?\n`, `\r?\n--`) are
+ *  fixed-shape (no `*`/`+`), so each runs in a single linear scan. */
+function extractMultipartJsonField(rawBody: string): HelloSignInboundBody | null {
+  const nameIdx = rawBody.indexOf('name="json"')
+  if (nameIdx === -1) return null
+  const afterName = rawBody.slice(nameIdx)
+  const sep = /\r?\n\r?\n/.exec(afterName)
+  if (!sep) return null
+  const partBody = afterName.slice(sep.index + sep[0].length)
+  const end = /\r?\n--/.exec(partBody)
+  if (!end) return null
+  try {
+    return JSON.parse(partBody.slice(0, end.index)) as HelloSignInboundBody
+  } catch {
+    return null
+  }
+}
+
 /** Generic HMAC provider — for the long-tail webhook source where the
  *  caller has standardised on a single sha256-of-body scheme. Header
  *  `X-Signature` by default; override at provider-build time if needed. */

src/webhooks/router.ts

@@ -84,6 +84,13 @@ export interface WebhookProvider {
     headers: WebhookHeaders
     now?: number
   }): WebhookEnvelope[] | Promise<WebhookEnvelope[]>
+  /** Optional provider-specific 200 ACK the router returns on a verified
+   *  delivery, in place of the default `{ received, total }` JSON. Dropbox Sign
+   *  acknowledges a delivery only when the body is exactly
+   *  'Hello API Event Received' and retries otherwise; this lets such a
+   *  provider declare the body/headers it needs. The frozen status contract is
+   *  unchanged — only the 200 body/headers are customized. */
+  successResponse?: { body: string; headers?: Record<string, string> }
 }
 
 export interface WebhookIdempotencyStore {
@@ -196,6 +203,13 @@ export class WebhookRouter {
       void this.deliverEach(accepted)
     })
 
+    if (provider.successResponse) {
+      return {
+        status: 200,
+        body: provider.successResponse.body,
+        headers: provider.successResponse.headers,
+      }
+    }
     return { status: 200, body: { received: accepted.length, total: events.length } }
   }