Webhooks

​

Créer un webhook

​

Événements

​

Payload

{
  "event": "quote.update",
  "workspace_id": "990e8400-e29b-41d4-a716-446655440004",
  "associated_object_id": "550e8400-e29b-41d4-a716-446655440000",
  "associated_object_type": "quote",
  "secret": "the-secret-you-entered"
}

​

Sécuriser votre endpoint

1. Définissez un Secret long et aléatoire sur le webhook.
2. Dans votre endpoint, comparez le champ secret du corps JSON à la valeur que vous avez stockée, et rejetez la requête (par exemple avec 401) si elles diffèrent.
3. N’exposez votre endpoint qu’en HTTPS, pour que le secret soit chiffré en transit.

app.post('/qwoty/webhook', express.json(), (req, res) => {
  if (req.body.secret !== process.env.QWOTY_WEBHOOK_SECRET) {
    return res.sendStatus(401)
  }
  res.sendStatus(200) // answer first
  queue.push(req.body) // then process asynchronously
})

​

Livraison

• Qwoty fait une seule tentative par événement et par endpoint. Il n’y a aucune nouvelle tentative : une livraison échouée n’est pas renvoyée.
• La requête expire au bout de 10 secondes. Tout statut autre que 2xx, tout délai dépassé ou toute erreur réseau compte comme un échec et s’affiche comme Échec dans la colonne Dernière livraison.
• L’ordre des événements n’est pas garanti.

​

Bonnes pratiques

• Répondez vite. Renvoyez immédiatement un 2xx et faites le traitement de manière asynchrone, bien en deçà du délai de 10 secondes.
• Récupérez l’état le plus récent. Le payload ne fait qu’identifier l’objet : lisez-le via l’API (par exemple Récupérer un devis ou Récupérer un client) avant d’agir.
• Soyez idempotent. Un même objet peut déclencher plusieurs événements update d’affilée ; assurez-vous que traiter deux fois le même événement est sans conséquence.
• Réconciliez régulièrement. Les livraisons échouées n’étant pas renvoyées, lancez une synchronisation périodique avec les endpoints de liste (par exemple Lister les devis) si vous ne pouvez pas vous permettre de manquer un événement.