Boas Práticas

Siga estas práticas para construir handlers de webhook confiáveis e prontos para produção.

Responda Rapidamente

Retorne um código de status 2xx o mais rápido possível. O GitScrum espera uma resposta dentro de 30 segundos. Se seu processamento demorar mais, confirme o recebimento imediatamente e processe de forma assíncrona.

Processamento Baseado em Fila

Desacople o recebimento do processamento usando uma fila de mensagens:

const Queue = require('bull');
const webhookQueue = new Queue('webhooks');

app.post('/webhooks/gitscrum', (req, res) => {
  // Acknowledge immediately
  res.status(200).json({ received: true });

  // Queue for async processing
  webhookQueue.add(req.body);
});

webhookQueue.process(async (job) => {
  const event = job.data;
  // Heavy processing here: database writes, API calls, notifications
  await processWebhook(event);
});

from celery import Celery

celery_app = Celery('webhooks', broker='redis://localhost:6379')

@app.route('/webhooks/gitscrum', methods=['POST'])
def webhook():
    event = request.get_json()

    # Acknowledge immediately
    process_webhook.delay(event)

    return jsonify({"received": True}), 200

@celery_app.task
def process_webhook(event):
    # Heavy processing here
    pass

Trate Duplicatas

O mesmo evento pode ser entregue mais de uma vez. Projete seu handler para ser idempotente — processar o mesmo evento duas vezes deve produzir o mesmo resultado.

Use o UUID como Chave de Idempotência

const processedEvents = new Set(); // Use Redis in production

webhookQueue.process(async (job) => {
  const { data } = job.data;
  const eventId = data.uuid;

  // Skip if already processed
  if (processedEvents.has(eventId)) {
    console.log(`Skipping duplicate: ${eventId}`);
    return;
  }

  processedEvents.add(eventId);
  await processWebhook(job.data);
});

Tratamento de Erros

Capture Todas as Exceções

Nunca deixe seu handler de webhook falhar. Envolva o processamento em tratamento de erros:

app.post('/webhooks/gitscrum', async (req, res) => {
  try {
    // Always respond 200 first
    res.status(200).json({ received: true });

    await processWebhook(req.body);
  } catch (error) {
    console.error('Webhook processing error:', error);
    // Log the error but don't crash the server
  }
});

Registre Tudo

Registre todos os webhooks recebidos para depuração e auditoria:

app.post('/webhooks/gitscrum', (req, res) => {
  const timestamp = new Date().toISOString();
  const headers = {
    'x-header': req.headers['x-header'],
    'user-agent': req.headers['user-agent'],
  };

  console.log(JSON.stringify({
    timestamp,
    headers,
    body: req.body,
  }));

  res.status(200).json({ received: true });
});

Monitoramento

Acompanhe Taxas de Sucesso de Entrega

Monitore seu endpoint de webhook para:

• Tempo de resposta (mantenha abaixo de 5 segundos)
• Taxas de erro (respostas 5xx)
• Tamanho do payload
• Profundidade da fila de processamento

Endpoint de Health Check

Adicione um health check junto ao seu endpoint de webhook:

app.get('/webhooks/health', (req, res) => {
  res.status(200).json({
    status: 'healthy',
    queue_depth: webhookQueue.getJobCount(),
    uptime: process.uptime(),
  });
});

Filtragem de Eventos

Se você usar a mesma URL de endpoint para múltiplos eventos, filtre verificando a estrutura do payload:

app.post('/webhooks/gitscrum', (req, res) => {
  res.status(200).json({ received: true });

  const { data } = req.body;

  // Route based on payload structure
  if (data.workflow) {
    handleTaskEvent(data);
  } else if (data.time_box) {
    handleSprintEvent(data);
  } else if (data.acceptance_criteria) {
    handleUserStoryEvent(data);
  }
});

Separação de Ambientes

Use endpoints de webhook diferentes para ambientes diferentes:

Configure projetos GitScrum separados para cada ambiente e aponte os webhooks para o endpoint correspondente.

Testes com ngrok

Durante o desenvolvimento, use uma ferramenta de tunelamento como ngrok para expor seu servidor local:

# Start your local server on port 3000
node server.js

# In another terminal, start ngrok
ngrok http 3000

Copie a URL HTTPS do ngrok e cole na configuração de webhook do GitScrum. Isso permite testar webhooks contra seu servidor de desenvolvimento local.

Relacionado

• Início Rápido — Configure seu primeiro webhook
• Segurança — Proteja seus endpoints de webhook
• Solução de Problemas — Problemas comuns e soluções