Bonnes Pratiques

Suivez ces pratiques pour construire des handlers de webhook fiables et prêts pour la production.

Répondez Rapidement

Retournez un code de statut 2xx le plus rapidement possible. GitScrum attend une réponse dans les 30 secondes. Si votre traitement prend plus de temps, confirmez la réception immédiatement et traitez de manière asynchrone.

Traitement Basé sur une File d'Attente

Découplez la réception du traitement en utilisant une file de messages :

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

Gérez les Doublons

Le même événement peut être livré plus d'une fois. Concevez votre handler pour être idempotent — traiter le même événement deux fois doit produire le même résultat.

Utilisez l'UUID comme Clé d'Idempotence

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);
});

Gestion des Erreurs

Capturez Toutes les Exceptions

Ne laissez jamais votre handler de webhook échouer. Enveloppez le traitement dans la gestion des erreurs :

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
  }
});

Enregistrez Tout

Enregistrez tous les webhooks reçus pour le débogage et l'audit :

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 });
});

Surveillance

Suivez les Taux de Réussite de Livraison

Surveillez votre endpoint de webhook pour :

• Temps de réponse (maintenez en dessous de 5 secondes)
• Taux d'erreur (réponses 5xx)
• Taille du payload
• Profondeur de la file de traitement

Endpoint de Vérification de Santé

Ajoutez une vérification de santé à côté de votre endpoint de webhook :

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

Filtrage des Événements

Si vous utilisez la même URL d'endpoint pour plusieurs événements, filtrez en vérifiant la structure du 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);
  }
});

Séparation des Environnements

Utilisez des endpoints de webhook différents pour différents environnements :

Configurez des projets GitScrum séparés pour chaque environnement et pointez les webhooks vers l'endpoint correspondant.

Tests avec ngrok

Pendant le développement, utilisez un outil de tunneling comme ngrok pour exposer votre serveur local :

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

# In another terminal, start ngrok
ngrok http 3000

Copiez l'URL HTTPS de ngrok et collez-la dans la configuration de webhook de GitScrum. Cela permet de tester les webhooks contre votre serveur de développement local.

Associé

• Démarrage Rapide — Configurez votre premier webhook
• Sécurité — Protégez vos endpoints de webhook
• Dépannage — Problèmes courants et solutions