Configurer et inspecter les webhooks

Les webhooks sont des appels HTTP (callbacks) que notre serveur adresse au vôtre, de manière asynchrone, lorsqu’un événement important se produit (par exemple, un devis a été approuvé ou payé).

Enregistrer un endpoint

Pour recevoir des webhooks, exposez une route POST sur votre serveur (par exemple https://api.votreentreprise.com/webhooks/cord).

1. Activez le Mode développeur dans Votre compte › Préférences. La pastille Développeurs apparaît dans le coin inférieur droit : ouvrez-la (ou appuyez sur W) et accédez à l’onglet Webhooks du Workbench (/app?wb=webhooks).
2. Cliquez sur Ajouter un endpoint et choisissez les événements : Tous les événements, une famille complète ou des événements individuels. Le champ de recherche filtre les 41 événements par nom.
3. Saisissez votre URL, publique et en HTTPS, puis cliquez sur Créer l’endpoint. Le secret de signature n’est affiché qu’une seule fois : conservez-le.

Événements disponibles

Cord émet des événements liés au cycle de vie du devis et, séparément, à celui de la facture en tant qu’objet à part entière (voir Facturation et l’API) :

• quote.sent — le devis a été envoyé au client.
• quote.viewed — le client l’a ouvert.
• quote.approved — le client l’a approuvé.
• quote.rejected — le client l’a refusé.
• quote.updated — il a été modifié et renvoyé.
• quote.expired — il a expiré sans réponse.
• quote.deleted — un brouillon a été supprimé.
• quote.paid — il a été intégralement payé.
• payment.partial — un acompte, un solde ou une échéance a été reçu sans couvrir le total.
• payment.failed — un paiement récurrent a échoué.
• invoice.issued, invoice.stamped — la facture d’un devis a été émise : facture commerciale hors du Mexique ou CFDI timbré.
• invoice.finalized, invoice.sent, invoice.paid, invoice.payment_failed, invoice.voided, invoice.marked_uncollectible, invoice.overdue — cycle de vie d’une facture créée comme ressource à part entière via /api/v1/facturas.
• quote.created, quote.approval_requested, quote.approval_decided, quote.comment_added — un devis a été créé, une validation interne a été demandée ou tranchée, ou quelqu’un a écrit dans la conversation.
• client.created, client.updated, client.deleted, product.created, product.updated, product.deleted — modifications de votre répertoire clients et de votre catalogue.
• task.created, task.completed, promise.created, promise.kept, promise.broken — tâches et promesses de paiement.
• dispute.created, dispute.closed, refund.succeeded, refund.failed, payout.paid, payout.failed, account.updated — litiges, remboursements, versements et modifications de votre compte d’encaissement.

Avec Tous les événements, l’endpoint reçoit aussi les événements que Cord ajoutera ultérieurement.

Le corps est au format JSON : { "id": "evt_...", "event": "quote.paid", "created_at": "...", "data": { "id", "folio", "status", "moneda", "total", "cliente", "cliente_id", "link_publico" } }. L’id de l’événement reste stable d’une nouvelle tentative à l’autre et lors d’un renvoi manuel depuis le Workbench — utilisez-le pour dédupliquer côté serveur.

Vérification de la signature

Validez toujours la signature pour vous assurer que l’événement provient bien de Cord. Chaque livraison inclut X-Cord-Signature-V1 (avec horodatage, protection contre la rejouabilité) et, pour la compatibilité, l’ancienne signature X-Cord-Signature (sans horodatage). Le nom de l’événement est transmis dans X-Cord-Event et son id stable dans X-Cord-Event-Id/Idempotency-Key. Si vous utilisez Node, constructEvent de @flouviahq/node la valide pour vous ; si vous préférez la vérifier à la main dans n’importe quel langage, consultez le code de vérification.

Nouvelles tentatives et inspection

Le bouton Tester de chaque endpoint envoie une livraison de test : ping ou n’importe quel événement auquel il est abonné, avec des données d’exemple et "test": true au premier niveau du corps.

En dépliant un endpoint, vous voyez son journal de livraisons (statut, latence et réponse de chaque tentative) et, en ouvrant une livraison, ce que Cord a envoyé et ce que votre serveur a répondu. Si une livraison échoue, vous pouvez la réessayer depuis cet écran ou renvoyer l’événement depuis l’onglet Événements. L’historique des livraisons, les nouvelles tentatives et les renvois sont inclus dès l’offre Professionnel.