AdPilot · Corpus
T-027 — Integrations hub: BYO provider keys + outbound webhooks
T-027 — Integrations hub: BYO provider keys + outbound webhooks
Frozen spec for the T-027 build. Users already pay for generation providers; they point AdPilot at their own instead of double-paying, and AdPilot becomes a signed webhook producer for the wider marketing/sales stack.
Decisions
- Scope (Q1): all four modalities are storable; only the copy lane
resolves an active integration in the provider layer today
(
services/api/internal/gen/gen.go— before the env default). Test-connection does a realGET {baseUrl}/modelswith the stored key (5s timeout) against the user's own provider; tests use localhost httptest servers only — the sandbox rule (no ad-platform calls, no spend) holds. - Implementer — key protection: AES-256-GCM keyed by
SHA-256(ADPILOT_SECRET) (sandbox default constant documented in
services/api/internal/domain/integrations.go); storedenc:-prefixed with a random nonce; every API response carries onlyRedactAPIKey(first4 + •••• + last4). Tests assert the plaintext never appears in create/list responses or the stored column. - Implementer — outbound delivery: signature
X-AdPilot-Signature: sha256=HMAC(secret, body)viadomain.SignHex(shared with the inbound hook verify); ≤3 attempts with exponential backoff (base·2^n, capped 60s; base overridable for tests), 10s client timeout; every attempt lands in the delivery log; dispatch reaches only endpoints explicitly subscribed to the event. The rule engine's webhookOut action now dispatches realautomation.fireddeliveries (replacing the audit stub).
Surface-area deltas
services/api/internal/domain/integrations.go(+ triggers.go SignHex) — schema, crypto, whitelists, backoff.services/api/internal/store/integrations.go+services/api/internal/store/migrations/0008_integrations.sql— CRUD + ActiveIntegration resolution + delivery log.services/api/internal/api/handlers_integrations.go— CRUD, connection test, webhook endpoints, signed dispatcher; 10 new routes inservices/api/internal/api/server.go;WebhookBackoffBasetest knob.services/api/internal/api/handlers_automations.go— webhookOut wired to the dispatcher.apps/web-next/app/integrations/page.tsx+apps/web-next/lib/{api,types,demo}.ts— the integrations page (keys redacted, endpoints, test-send, delivery log) and demo-engine parity.services/api/internal/domain/triggers.go—SignHexextracted so the inbound verify and outbound sign share one implementation.apps/web-next/app/layout.tsx— nav link for the integrations page.apps/web-next/lib/api.ts,apps/web-next/lib/types.ts,apps/web-next/lib/demo.ts— client methods, types, demo parity.- Board rows
tasks/00-backlog/T-027-integrations-hub-webhooks.md/tasks/10-in-progress/T-027-integrations-hub-webhooks.mdand this spec filedocs/tech-spec/T-027.mdare bookkeeping. - Tests:
services/api/internal/domain/integrations_test.goandservices/api/internal/api/integrations_test.go.
Verification
Go gates: go test ./... (6/6 packages; 9 new test functions incl. a local
receiver verifying the HMAC signature and a retry-on-500 case). Web gate:
npm run build + jest + eslint. Live dispatch covered by the httptest
receiver tests (no external calls).
Out of scope
Real image/video/STT provider overrides, OAuth-style key vaulting, webhook signing-key rotation notification mail, ad-platform calls (sandbox rule).