feat(integrations): push Vercel deployment and uninstall events by webhook

Abierto
  • ¿Algo no está bien?
#422 1 comentario 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
35/100
Tipo de issue
Nueva funcionalidad
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
nextjs, playwright, typescript
Área
api, backend

Línea de trabajo

Start by reading the webhook contract from #28 and the existing adapter in src/lib/adapters/vercel/ to see how polling currently emits deployment events, then read docs/providers/vercel.md for the signature and envelope details. Work through the handler in order: constant-time HMAC SHA-1 verification of x-vercel-signature on the raw body, dedup on envelope id, team-to-connection mapping, then event mapping and integration-configuration.removed. Cover it with unit tests on recorded payloads plus the Playwright spec for the simulated provider; done is all acceptance boxes green under npm run lint, npm run typecheck, npm test.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

area: integrations blocked enhancement impact: medium priority: P1 size: S

Context

The Vercel adapter (#47, closed) polls deployments hourly. Eddie's decision on #28 (2026-11-14): webhooks first, polling as the backfill, and webhooks are in the MVP. Vercel can push without any new scope: the webhook URL lives on the integration, and deliveries are signed with the client secret the adapter already has.

From docs/providers/vercel.md, "Webhooks (Post-MVP)", checked against Vercel's docs on 2026-10-31:

Item Value
Where the URL lives One Webhook URL per integration, set in the Integrations Console, with event checkboxes
Signature x-vercel-signature: hex HMAC SHA-1 of the raw body, keyed with the integration's client secret. Rotating the secret changes the key
Envelope { type, id, createdAt, region, payload }. Deployment payloads carry payload.team.id, payload.project.id, payload.deployment.{id,url,name}, payload.target
Delivery 30 second timeout. Non-2xx responses are retried with backoff for up to 24 hours
Useful events deployment.created, deployment.succeeded, deployment.ready, deployment.error, deployment.canceled, project.created, project.removed, integration-configuration.removed
Not pushed Billing charges and usage. Spend stays polled

Plan

  1. Implement the Vercel webhook declaration from the contract #28 adds: verify x-vercel-signature against the raw body in constant time, deduplicate on the envelope id.
  2. Map payload.team.id (or the user id for a personal account) to the connection. Unknown teams are acknowledged and dropped.
  3. Deployment events become the event types the adapter already emits, so a deployment seen by webhook and then by polling shows once.
  4. integration-configuration.removed marks the connection as needing a reconnect at once.
  5. project.created and project.removed update the connection's accounts without a reconnect, if the adapter's accounts are projects; otherwise ignore them.
  6. Docs: docs/providers/vercel.md (rename the section to "Webhooks", update uninstall detection and self-hosted registration to set the Webhook URL and events), docs/operations/oauth-apps.md.

Acceptance criteria

  • A signed deployment delivery reaches the timeline within a minute, without waiting for a sync.
  • A deployment seen by webhook and by polling shows once.
  • Unsigned, wrongly signed, or repeated deliveries are rejected or ignored, and logged without their body.
  • integration-configuration.removed marks the connection as needing a reconnect.
  • Polling still runs and still fills in charges and any missed delivery.
  • Unit tests on recorded, sanitized payloads from Vercel's documented samples. No live calls in CI.
  • Playwright e2e: a signed delivery for the simulated Vercel provider appears on the timeline.

Files and areas

  • src/lib/adapters/vercel/ (webhook handler, schemas, fixtures, tests), the webhook route from #28, docs/providers/vercel.md, docs/operations/oauth-apps.md.
  • Non-goals: new scopes, domain events, and pushing spend (no webhook exists for it).

Verification

  • npm run lint, npm run typecheck, npm test
  • The Playwright spec for the simulated delivery.

Depends on

  • #28 Ingest provider webhooks (contract, route, deduplication)
  • #47 Add the Vercel adapter (closed)

Branch: <issue-number>-vercel-webhooks
Closes with a Closes #<issue-number> footer on the commit or pull request.

Model: anthropic/claude-opus-5-5 | Reasoning effort: unknown

Lenguaje dominante
TypeScript
Estrellas
1
Forks
1
Merge medio
6 h 56 min
PR fusionados (30 d)
136

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de eddiejaoude/StackDash

Todos los issues de eddiejaoude/StackDash

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.