Integraciones y webhooks

---
name: integraciones-y-webhooks
description: conectar tu app con las demás, en los dos sentidos.
---

# Integraciones y webhooks

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando
consumas APIs ajenas, recibas webhooks entrantes, emitas los tuyos o programes tareas.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- Tu app tiene que leer o escribir en Google, Slack, Notion, GitHub o similares.
- Algo de afuera debe avisarte cuando ocurre un evento (un pago, un mensaje, un commit).
- Hay trabajo que debe correr cada hora o cada noche sin que nadie lo dispare.
- Estás replicando una herramienta de automatización, publicación o sincronización.

Esta es el moat más citado del cementerio: el producto original no gana por su pantalla,
gana porque ya habla con Slack, Google Calendar, Stripe y otras cuarenta cosas, y porque
alguien las repara cada semana. Trátalo con esa seriedad.

## Cómo construirla

Usa este stack salvo que el proyecto ya tenga otro decidido: OAuth2 con tokens cifrados
en base de datos, endpoints de webhook idempotentes, **Vercel Cron** o **GitHub Actions**
programadas para lo periódico, **Inngest** o **BullMQ** solo cuando el volumen lo pida.

1. Integra un servicio, completo y bien, antes de intentar cinco a medias. La segunda
   integración te va a enseñar dónde abstraer, la primera todavía no.
2. Guarda access token y refresh token cifrados, con su fecha de expiración, y renuévalos
   antes de que caduquen.
3. Todo webhook entrante: verifica la firma, responde 200 rápido y procesa después. Si
   tardas, te reenvían el evento.
4. Haz el procesamiento idempotente por id de evento. Los duplicados no son una
   excepción, son la norma.
5. Para lo programado, empieza con un cron del proveedor (Vercel Cron, GitHub Actions) y
   una tabla de trabajos en Postgres. Solo agrega Inngest, Trigger.dev o BullMQ cuando
   esa tabla se te quede corta.
6. Registra cada llamada saliente fallida con su respuesta: sin ese registro, depurar una
   integración es adivinar.

## En qué te vas a trabar

- **Cada API cambia límites, alcances y políticas por su cuenta.** Las integraciones no
  se terminan, se mantienen; avísalo si te preguntan cuánto falta.
- **La revisión de app de Google o Slack puede tardar semanas** y pedir cosas que no
  anticipaste. Empieza ese trámite temprano, no al final.
- **Los límites de tasa se sienten hasta que tienes usuarios.** Agrupa peticiones y
  guarda en caché desde el inicio, no cuando llegue el primer 429.

## Criterio de terminado

No declares una integración lista hasta que sobreviva un webhook duplicado sin efecto
doble, un token expirado se renueve solo, y una llamada saliente fallida quede registrada
en vez de perderse en silencio.