Testes de contrato para webhooks e APIs: reduzindo regressão em integrações

Integração saudável no deploy não garante integração saudável amanhã. O contrato com o parceiro é vivo: ele renomeia um campo, troca um número por string, adiciona um nível de aninhamento ou versiona a API inteira. Nada disso aparece no seu teste unitário, porque seu mock foi escrito uma vez e congelado. O resultado clássico é a quebra silenciosa: o webhook chega, seu parser não acha o campo esperado, grava null e segue em frente sem erro. Em produção, isso vira pedido sem valor, mensagem sem destinatário ou status que nunca atualiza, e você só percebe quando o cliente reclama.

Teste de contrato ataca exatamente essa cegueira. Em vez de confiar que o payload continua igual, você afirma o formato esperado de forma explícita e executável. Quando o parceiro muda, o teste falha de propósito, no CI, com a mudança apontada campo a campo, e não em produção três dias depois.

Existem três abordagens com nomes parecidos que resolvem problemas diferentes. Escolher errado gera teste que dá trabalho e não pega a regressão certa. A tabela abaixo separa o papel de cada uma no contexto de quem consome um parceiro externo.

Para quem integra com um parceiro grande (Meta, gateways de pagamento, ERPs), o caso mais comum é o terceiro: você não controla o provider e nem sempre ele publica spec confiável. Então a defesa prática é validar todo payload recebido contra um schema seu e gravar contratos das respostas que você consome para detectar drift.

A primeira linha de defesa é nunca processar um webhook sem antes validar a forma. Com zod você declara o contrato esperado e, no momento que o payload diverge, recebe um erro descritivo apontando o campo, em vez de um null silencioso lá na frente. Abaixo, um schema para o payload de mensagem recebida do WhatsApp Cloud API.

// webhookSchema.js
const { z } = require('zod');

const messageSchema = z.object({
  from: z.string().min(8),
  id: z.string(),
  timestamp: z.string(),
  type: z.enum(['text', 'image', 'audio', 'document', 'interactive']),
  text: z.object({ body: z.string() }).optional(),
});

const valueSchema = z.object({
  messaging_product: z.literal('whatsapp'),
  metadata: z.object({
    display_phone_number: z.string(),
    phone_number_id: z.string(),
  }),
  messages: z.array(messageSchema).optional(),
  statuses: z.array(z.object({ id: z.string(), status: z.string() })).optional(),
});

const webhookSchema = z.object({
  object: z.literal('whatsapp_business_account'),
  entry: z.array(z.object({
    id: z.string(),
    changes: z.array(z.object({
      field: z.literal('messages'),
      value: valueSchema,
    })),
  })).min(1),
});

module.exports = { webhookSchema };

// no handler do webhook
const { webhookSchema } = require('./webhookSchema');

app.post('/webhook', (req, res) => {
  const parsed = webhookSchema.safeParse(req.body);

  if (!parsed.success) {
    // contrato violado: registre, alerte, mas devolva 200
    // para o parceiro nao reenviar em loop por erro de forma
    logger.error('payload fora do contrato', {
      issues: parsed.error.issues,
    });
    metrics.increment('webhook.contract_violation');
    return res.sendStatus(200);
  }

  enqueue(parsed.data); // so dado valido entra na fila
  return res.sendStatus(200);
});

O ponto fino: violação de contrato é diferente de erro de processamento. Devolva 200 para o parceiro não entrar em loop de reenvio, mas dispare métrica e alerta. Um pico em webhook.contract_violation logo após uma mudança do parceiro é o sinal mais cedo possível de que o payload mudou.

Validar o que entra resolve metade. A outra metade é o que você chama: quando você consome uma API externa, a resposta também tem contrato, e ele também muda. A tática é gravar a resposta esperada uma vez e comparar contra ela para detectar drift.

• Grave um snapshot da resposta real do parceiro em ambiente controlado, mascarando dados sensíveis e timestamps voláteis.
• Em cada execução, valide a resposta atual contra o schema derivado do snapshot, não byte a byte, mas estrutura, tipos e campos obrigatórios.
• Trate campo novo como drift informativo (loga e segue) e campo removido ou tipo trocado como drift que quebra (falha o teste).
• Rode esses testes contra um sandbox ou contrato gravado, nunca contra produção do parceiro, para não depender da disponibilidade dele no CI.
• Versione os snapshots no repositório: o diff do snapshot no pull request vira documentação viva de como a API do parceiro evoluiu.

// contractDrift.test.js
const { z } = require('zod');
const snapshot = require('./snapshots/order-response.json');

// schema derivado da resposta gravada
const orderSchema = z.object({
  id: z.string(),
  status: z.enum(['pending', 'paid', 'failed']),
  amount: z.number(),
  currency: z.string().length(3),
});

test('resposta do parceiro continua dentro do contrato', async () => {
  // em CI: usa o snapshot; em job dedicado: bate no sandbox
  const response = process.env.HIT_SANDBOX
    ? await fetchFromSandbox()
    : snapshot;

  const result = orderSchema.safeParse(response);
  expect(result.success).toBe(true);
});

Parceiros sérios versionam. A Graph API da Meta, por exemplo, expõe a versão na URL (/v21.0/) e deprecia versões antigas em janela conhecida. Tratar versão como detalhe escondido no código é receita para quebra na data de sunset. A migração tem que ser um processo, não um susto.

1. Fixe a versão explicitamente em um único lugar (variável de ambiente ou config), nunca espalhada por chamadas soltas no código.
2. Mantenha um teste de contrato por versão ativa, para que a nova versão seja validada lado a lado com a atual antes de virar a chave.
3. Quando o parceiro anunciar uma versão nova, suba um job que roda os contratos contra ela e mostra o diff de payload em relação à versão em uso.
4. Faça a migração em canary: aponte uma fração do tráfego para a versão nova, observe métricas e contrato, e só então promova para 100%.
5. Acompanhe a data de depreciação da versão antiga como item de backlog com prazo, e deixe o teste de contrato falhar de propósito quando faltar pouco para o sunset.

Parceiro anuncia v(N+1)
        |
        v
Contrato v(N) [atual] ---+
                         |--> diff de payload --> revisão
Contrato v(N+1) [novo] --+
        |
        v
Canary 5% --> metricas ok? --> promove 100% --> deprecia v(N)

Teste de contrato só reduz regressão se rodar no momento certo. Ele vive em dois lugares: no CI de todo pull request, validando schema de webhook e snapshots gravados sem depender do parceiro, e em um job agendado que bate no sandbox do parceiro para pegar mudanças que ainda não chegaram ao seu código.

• No CI de pull request: valide schemas de webhook e snapshots gravados; rápido, determinístico e sem rede externa.
• Antes do deploy: o pipeline deve barrar a promoção se algum contrato estiver vermelho, tratando contrato quebrado como build quebrado.
• Em job agendado (nightly): bata no sandbox do parceiro para detectar drift que o snapshot ainda não capturou, e abra alerta quando divergir.
• Em produção: a validação do payload recebido continua ligada como última linha, emitindo métrica de violação de contrato em tempo real.

# .github/workflows/contract.yml
name: contract-tests
on:
  pull_request:
  schedule:
    - cron: '0 6 * * *' # nightly contra o sandbox

jobs:
  contract:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm ci
      # PR: snapshots e schemas, sem rede externa
      - run: npm run test:contract
      # nightly: bate no sandbox do parceiro
      - if: github.event_name == 'schedule'
        run: npm run test:contract:sandbox
        env:
          HIT_SANDBOX: 'true'