feat(webhooks): create subscriptions idempotently

Author: alpesdigital-adm

README.md

@@ -137,8 +137,7 @@ O envelope versionado e o catálogo inicial de eventos podem ser descobertos em
 `GET /v1/events/catalog`. O catálogo referencia o JSON Schema público do envelope
 e contém somente metadados estáticos, por isso não exige autenticação. A presença
 de um tipo no catálogo não significa que ele já esteja sendo emitido: cada
-transição precisa ser conectada ao outbox, e subscriptions, assinatura e entrega
-at-least-once serão adicionadas nas próximas slices de F0.038.
+transição ainda precisa ser conectada explicitamente ao outbox.
 
 A criação de projeto já persiste `project.created` e `project.version.created`
 no outbox, atomicamente com o projeto, sua versão inicial e o registro de
@@ -160,6 +159,13 @@ HTTPS e seu fingerprint; secrets são apenas metadados de versão, fingerprint e
 estado, sem `keyRef` ou material criptográfico. Os filtros exatos da subscription
 são visíveis porque definem o comportamento contratado da entrega.
 
+Novas subscriptions podem ser criadas por `POST /v1/webhooks/subscriptions`
+para um endpoint existente. O command exige `Idempotency-Key`: repetir endpoint
+e filtro idênticos com a mesma chave devolve o recurso original, enquanto reutilizar
+a chave para outro filtro ou tentar duplicar o filtro com outra chave retorna
+conflito explícito. A criação nasce ativa somente quando o endpoint está ativo;
+endpoints ainda em challenge produzem uma subscription pendente.
+
 O status de uma subscription pode ser alterado por
 `PUT /v1/webhooks/subscriptions/{subscriptionId}/status`. A resposta de consulta
 fornece uma revisão opaca que deve ser enviada como `baseRevision`: alterações

TODO.md

@@ -496,7 +496,7 @@
 - [x] Modelar endpoint, subscription, secret, filter e delivery attempt. Evidência F0-034: domínios canônicos, registro transacional, cinco tabelas, constraints e regressões de segurança.
 - [x] Implementar challenge, assinatura, timestamp e anti-replay. Evidência F0-035/F0-036: challenge durável one-shot, HMAC dos bytes exatos, janela de timestamp, receipt anti-replay e transporte HTTPS pinado com resolução DNS fail-closed.
 - [x] Implementar at-least-once, backoff, dead-letter e replay controlado. Evidência F0-031/F0-046: render possui lease/fencing, backoff, checkpoint, dead-letter e retry manual; webhooks possuem outbox/fan-out, claim/lease/fencing, dispatch assinado, transporte DNS-pinado, heartbeat, discovery, coordenação durável de shards, secret provider configurado, entrypoint operacional, backoff, dead-letter e replay idempotente individual ou por evento exato. Replay por intervalo permanece enhancement administrativo separado.
-- [ ] Criar UI/API administrativa de status, attempts e rotação de secret. Parcial F0-042/F0-044/F0-047/F0-048/F0-049: API externa lista/lê endpoints, subscriptions e deliveries, executa replay e altera lifecycle de endpoints/subscriptions; UI, criação/challenge e rotação de secret continuam abertas.
+- [ ] Criar UI/API administrativa de status, attempts e rotação de secret. Parcial F0-042/F0-044/F0-047/F0-048/F0-049/F0-050: API externa lista/lê endpoints, subscriptions e deliveries, cria subscriptions com filtros exatos, executa replay e altera lifecycle de endpoints/subscriptions; UI, criação/challenge de endpoint e rotação de secret continuam abertas.
 - [x] Criar integration tests de duplicação, timeout, assinatura inválida e replay. Evidência F0-035/F0-043: assinatura adulterada, anti-replay durável, deadline absoluto, DNS/rebinding, claim concorrente, lease/fencing, retry/dead-letter e replay administrativo idempotente estão cobertos em contratos, Prisma e HTTP.
 
 ### F0.039 — Idempotência e concorrência externa [FR-245]
@@ -539,7 +539,7 @@
 ### F0.043 — Governança da API [FR-249]
 
 - [ ] Criar administração de clients, scopes, secrets, environments e status.
-- [ ] Criar administração de webhooks, subscriptions e delivery diagnostics. Parcial F0-042/F0-044/F0-047/F0-048/F0-049: capabilities de endpoints, subscriptions, deliveries e replay entregam consulta, lifecycle com cascatas e replay workspace-scoped; criação, challenge, rotação e UI continuam abertas.
+- [ ] Criar administração de webhooks, subscriptions e delivery diagnostics. Parcial F0-042/F0-044/F0-047/F0-048/F0-049/F0-050: capabilities de endpoints, subscriptions, deliveries e replay entregam consulta, criação idempotente de subscription, lifecycle com cascatas e replay workspace-scoped; criação/challenge de endpoint, rotação e UI continuam abertas.
 - [ ] Implementar rate limits, quotas, concurrency e spend budgets por client/workspace.
 - [ ] Criar usage e audit queries paginadas com redaction.
 - [ ] Criar sandbox isolado com provider fakes e custos simulados.
@@ -3991,7 +3991,7 @@ Limites explícitos desta slice:
 
 ### Slice F0-049 — Lifecycle e cascatas de endpoints de webhook
 
-**Status:** concluído localmente em 15 de julho de 2026; ainda não commitado.
+**Status:** publicado no `main` em 15 de julho de 2026 (`47faab8`); hosted CI `29445313005` aprovada.
 
 Entregas:
 
@@ -4026,3 +4026,34 @@ Limites explícitos desta slice:
 - criação e alteração de filtros de subscription permanecem abertas;
 - rotação de signing secret e reload dinâmico de provider permanecem abertas;
 - UI administrativa, audit query, métricas e alertas operacionais continuam futuros.
+
+### Slice F0-050 — Criação externa idempotente de subscriptions
+
+**Status:** concluído localmente em 15 de julho de 2026; ainda não commitado.
+
+Entregas:
+
+- capability `apollo.webhooks.subscriptions.create` expõe `POST /v1/webhooks/subscriptions` sob `webhooks:admin`;
+- body fechado aceita endpoint, tipos do catálogo e IDs de recurso opcionais, sempre convertidos para filtro canônico exato;
+- `Idempotency-Key` obrigatória é vinculada a workspace, API client, endpoint e hash do filtro;
+- primeira criação retorna 201; repetição idêntica retorna o mesmo recurso com 200 e `replayed: true`;
+- mesma chave com payload diferente retorna `IDEMPOTENCY_PAYLOAD_MISMATCH`; filtro idêntico com outra chave retorna `WEBHOOK_SUBSCRIPTION_ALREADY_EXISTS`;
+- ledger e subscription são gravados atomicamente em transação serializável;
+- endpoint ativo cria subscription ativa; endpoint pendente cria subscription pendente; suspenso ou revogado rejeita o command;
+- resposta reutiliza presenter redigido e não expõe workspace, URL, `filterHash`, secrets ou ledger;
+- ADR-039 formaliza idempotência, unicidade exata, estados iniciais e concorrência.
+
+Regressões e evidências locais:
+
+- suíte global passa com 108 testes; 40 são contratos de webhook;
+- integração Prisma cobre criação pendente, replay, payload divergente, filtro duplicado e ausência de duplicação;
+- jornada HTTP cobre OpenAPI, 201/200, chave ausente, replay, conflitos distintos e 403 sem scope;
+- contratos públicos passam com 38 capabilities, 46 schemas, 62 exemplos e 34 paths;
+- build registra `POST /v1/webhooks/subscriptions` junto do GET existente;
+- integração de webhook e jornada pública passam no protótipo SQLite.
+
+Limites explícitos desta slice:
+
+- criação, alteração de URL e challenge público de endpoint continuam abertos;
+- alteração de filtro de subscription permanece um command futuro separado;
+- rotação de signing secret, UI administrativa, audit query, métricas e alertas continuam futuros.

docs/adr/ADR-039-idempotent-webhook-subscription-creation.md

@@ -0,0 +1,37 @@
+# ADR-039 — Criação idempotente de subscriptions de webhook
+
+> **Status:** Accepted
+>
+> **Data:** 15 de julho de 2026
+
+## Contexto
+
+A administração externa já consultava subscriptions e alterava seu lifecycle, mas ainda não conseguia anexar um novo filtro a um endpoint existente. Agentes externos precisam repetir uma chamada após timeout sem criar recursos duplicados, distinguir replay de conflito e receber o mesmo resultado original. A criação também precisa respeitar o estado do endpoint no mesmo instante em que persiste a subscription.
+
+## Decisão
+
+- A capability `apollo.webhooks.subscriptions.create` expõe `POST /v1/webhooks/subscriptions` sob `webhooks:admin` e confirmação humana.
+- O body fechado aceita `endpointId`, `eventTypes` e `resourceIds` opcional; tipos de evento devem pertencer ao catálogo público e ambos os filtros são ordenados e hasheados canonicamente.
+- `Idempotency-Key` é obrigatório, possui de 1 a 128 caracteres ASCII imprimíveis e é isolado por workspace e API client.
+- O fingerprint vincula a chave ao endpoint e ao hash do filtro canônico. A mesma chave e payload devolve a subscription original com HTTP 200 e `replayed: true`; payload diferente devolve 409.
+- A primeira criação devolve HTTP 201 e `replayed: false`. O ledger e a subscription são persistidos atomicamente em transação serializável.
+- Uma subscription criada em endpoint ativo nasce ativa; em endpoint pendente de verificação nasce pendente. Endpoint suspenso ou revogado rejeita a criação com 409.
+- O par endpoint + filtro exato é único. Outra chave tentando reproduzir o mesmo filtro recebe `WEBHOOK_SUBSCRIPTION_ALREADY_EXISTS`, sem adotar silenciosamente um recurso anterior.
+- Endpoint, API client e workspace são verificados dentro da transação. Replays reidratam o recurso por workspace e falham de forma fechada se o resultado persistido não existir.
+- A resposta pública usa o presenter redigido: não expõe workspace, URL, `filterHash`, secret, ledger ou detalhes da transação.
+
+## Consequências
+
+- Agentes podem repetir chamadas ambíguas de rede com segurança e obter identidade estável.
+- A unicidade natural do filtro não substitui o ledger: ela bloqueia duplicatas, enquanto a chave preserva a semântica do request e sua resposta.
+- Criações concorrentes convergem pelo ledger ou falham explicitamente por filtro duplicado/serialização, sem estado parcial.
+- Alteração de filtro continua sendo uma operação futura separada; não há atualização implícita durante a criação.
+
+## Evidências exigidas
+
+- criação em endpoint ativo e pendente escolhe o estado correto;
+- replay retorna o mesmo ID e não cria uma segunda linha;
+- mesma chave com payload diferente e filtro duplicado com outra chave retornam conflitos distintos;
+- endpoint ausente/inativo, body inválido, chave ausente e falta de scope falham antes de efeitos indevidos;
+- OpenAPI declara body, header idempotente e respostas 200/201;
+- contratos unitários, Prisma e jornada HTTP exercitam a implementação real.

src/app/v1/webhooks/subscriptions/route.ts

@@ -1,9 +1,14 @@
+import { randomUUID } from 'node:crypto'
 import { NextRequest, NextResponse } from 'next/server'
 
 import { requireScope } from '@/v2/application/authenticate-api-client'
+import { createWebhookSubscriptionService } from '@/v2/application/create-webhook-subscription'
 import { listWebhookSubscriptionsService } from '@/v2/application/list-webhook-administration'
 import { DomainError } from '@/v2/domain/errors'
-import { createWebhookAdministrationQueryRepository } from '@/v2/infrastructure/repository-factory'
+import {
+  createWebhookAdministrationQueryRepository,
+  createWebhookSubscriptionCreationRepository,
+} from '@/v2/infrastructure/repository-factory'
 import { authenticateExternalRequest } from '@/v2/public-api/authentication'
 import { publicApiHeaders, resolveRequestId, respondPublicError } from '@/v2/public-api/errors'
 import { presentSuccess, presentWebhookSubscription } from '@/v2/public-api/presenters'
@@ -33,3 +38,67 @@ export async function GET(request: NextRequest) {
     }), { status: 200, headers: publicApiHeaders(requestId) })
   } catch (error) { return respondPublicError(error, requestId) }
 }
+
+export async function POST(request: NextRequest) {
+  const requestId = resolveRequestId(request)
+  try {
+    const actor = await authenticateExternalRequest(request)
+    requireScope(actor, 'webhooks:admin')
+    const idempotencyKey = request.headers.get('idempotency-key')?.trim() ?? ''
+    let body: Record<string, unknown>
+    try {
+      const value = await request.json() as unknown
+      if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new DomainError('INVALID_ARGUMENT', 'Request body must be an object')
+      }
+      body = value as Record<string, unknown>
+    } catch (error) {
+      if (error instanceof DomainError) throw error
+      throw new DomainError('INVALID_ARGUMENT', 'Request body must be valid JSON')
+    }
+    const allowed = new Set(['endpointId', 'eventTypes', 'resourceIds'])
+    for (const name of Object.keys(body)) {
+      if (!allowed.has(name)) throw new DomainError('INVALID_ARGUMENT', `${name} is not supported`)
+    }
+    if (typeof body.endpointId !== 'string') {
+      throw new DomainError('INVALID_ARGUMENT', 'endpointId must be a string')
+    }
+    if (!Array.isArray(body.eventTypes) || !body.eventTypes.every((value) => typeof value === 'string')) {
+      throw new DomainError('INVALID_ARGUMENT', 'eventTypes must be an array of strings')
+    }
+    if (
+      body.resourceIds !== undefined &&
+      (!Array.isArray(body.resourceIds) || !body.resourceIds.every((value) => typeof value === 'string'))
+    ) {
+      throw new DomainError('INVALID_ARGUMENT', 'resourceIds must be an array of strings')
+    }
+
+    const createSubscription = createWebhookSubscriptionService({
+      repository: createWebhookSubscriptionCreationRepository(),
+      clock: () => new Date(),
+      createId: (kind) => kind === 'webhook-subscription'
+        ? randomUUID()
+        : `${kind}-${randomUUID()}`,
+    })
+    const result = await createSubscription({
+      workspaceId: actor.workspaceId,
+      endpointId: body.endpointId,
+      eventTypes: body.eventTypes,
+      ...(body.resourceIds ? { resourceIds: body.resourceIds as string[] } : {}),
+      createdByClientId: actor.clientId,
+      idempotencyKey,
+    })
+    return NextResponse.json(
+      presentSuccess({
+        subscription: presentWebhookSubscription(result.subscription),
+        replayed: result.replayed,
+      }),
+      {
+        status: result.replayed ? 200 : 201,
+        headers: publicApiHeaders(requestId),
+      },
+    )
+  } catch (error) {
+    return respondPublicError(error, requestId)
+  }
+}

src/v2/application/create-webhook-subscription.ts

@@ -0,0 +1,90 @@
+import { assertDomain } from '../domain/errors.ts'
+import { createWebhookSubscription } from '../domain/webhook.ts'
+import type {
+  WebhookSubscriptionCreationRepository,
+  WebhookSubscriptionCreationResult,
+} from './ports/webhook-subscription-creation-repository.ts'
+import { calculateVersionHash } from './version-hash.ts'
+
+export type WebhookSubscriptionCreationEntityKind =
+  | 'webhook-subscription'
+  | 'idempotency-record'
+
+export interface CreateWebhookSubscriptionRequest {
+  workspaceId: string
+  endpointId: string
+  eventTypes: readonly string[]
+  resourceIds?: readonly string[]
+  createdByClientId: string
+  idempotencyKey: string
+  idempotencyTtlSeconds?: number
+}
+
+export interface CreateWebhookSubscriptionDependencies {
+  repository: WebhookSubscriptionCreationRepository
+  clock: () => Date
+  createId: (kind: WebhookSubscriptionCreationEntityKind) => string
+}
+
+const DEFAULT_IDEMPOTENCY_TTL_SECONDS = 24 * 60 * 60
+const PRINTABLE_IDEMPOTENCY_KEY = /^[\x21-\x7e]+$/
+
+export function createWebhookSubscriptionService(
+  dependencies: CreateWebhookSubscriptionDependencies,
+) {
+  return async function execute(
+    request: CreateWebhookSubscriptionRequest,
+  ): Promise<Readonly<WebhookSubscriptionCreationResult>> {
+    const workspaceId = request.workspaceId.trim()
+    const endpointId = request.endpointId.trim()
+    const clientId = request.createdByClientId.trim()
+    const idempotencyKey = request.idempotencyKey.trim()
+    const ttlSeconds = request.idempotencyTtlSeconds ?? DEFAULT_IDEMPOTENCY_TTL_SECONDS
+
+    assertDomain(workspaceId.length > 0, 'INVALID_ARGUMENT', 'workspaceId is required')
+    assertDomain(clientId.length > 0, 'INVALID_ARGUMENT', 'createdByClientId is required')
+    assertDomain(
+      idempotencyKey.length >= 1 && idempotencyKey.length <= 128 && PRINTABLE_IDEMPOTENCY_KEY.test(idempotencyKey),
+      'INVALID_ARGUMENT',
+      'Idempotency-Key must contain 1 to 128 printable ASCII characters',
+    )
+    assertDomain(
+      Number.isInteger(ttlSeconds) && ttlSeconds >= 60 && ttlSeconds <= 7 * 24 * 60 * 60,
+      'INVALID_ARGUMENT',
+      'idempotency ttlSeconds must be between 60 seconds and 7 days',
+    )
+
+    const now = dependencies.clock()
+    const createdAt = now.toISOString()
+    const subscription = createWebhookSubscription({
+      id: dependencies.createId('webhook-subscription'),
+      workspaceId,
+      endpointId,
+      status: 'active',
+      filter: {
+        eventTypes: request.eventTypes,
+        ...(request.resourceIds ? { resourceIds: request.resourceIds } : {}),
+      },
+      createdByClientId: clientId,
+      createdAt,
+    })
+    const requestFingerprint = calculateVersionHash({
+      action: 'webhook-subscription-create/v1',
+      endpointId: subscription.endpointId,
+      filterHash: subscription.filter.hash,
+    })
+
+    return dependencies.repository.createOrReplay({
+      subscription,
+      idempotency: {
+        id: dependencies.createId('idempotency-record'),
+        workspaceId,
+        clientId,
+        key: idempotencyKey,
+        requestFingerprint,
+        requestedAt: createdAt,
+        expiresAt: new Date(now.getTime() + ttlSeconds * 1000).toISOString(),
+      },
+    })
+  }
+}

src/v2/application/ports/webhook-subscription-creation-repository.ts

@@ -0,0 +1,27 @@
+import type { WebhookSubscription } from '../../domain/webhook.ts'
+
+export interface WebhookSubscriptionCreationIdempotency {
+  id: string
+  workspaceId: string
+  clientId: string
+  key: string
+  requestFingerprint: string
+  requestedAt: string
+  expiresAt: string
+}
+
+export interface WebhookSubscriptionCreationBundle {
+  subscription: Readonly<WebhookSubscription>
+  idempotency: Readonly<WebhookSubscriptionCreationIdempotency>
+}
+
+export interface WebhookSubscriptionCreationResult {
+  subscription: Readonly<WebhookSubscription>
+  replayed: boolean
+}
+
+export interface WebhookSubscriptionCreationRepository {
+  createOrReplay(
+    bundle: Readonly<WebhookSubscriptionCreationBundle>,
+  ): Promise<Readonly<WebhookSubscriptionCreationResult>>
+}

src/v2/domain/errors.ts

@@ -33,6 +33,8 @@ export const DOMAIN_ERROR_CODES = [
   'WEBHOOK_ENDPOINT_TRANSITION_REJECTED',
   'WEBHOOK_ENDPOINT_REVISION_MISMATCH',
   'WEBHOOK_SUBSCRIPTION_NOT_FOUND',
+  'WEBHOOK_SUBSCRIPTION_ALREADY_EXISTS',
+  'WEBHOOK_SUBSCRIPTION_CREATE_REJECTED',
   'WEBHOOK_SUBSCRIPTION_TRANSITION_REJECTED',
   'WEBHOOK_SUBSCRIPTION_REVISION_MISMATCH',
   'WEBHOOK_DELIVERY_NOT_FOUND',