Webhooks

Pourquoi utiliser les webhooks ?

Au lieu que votre système (un ERP, un flux Zapier/Make ou votre propre backend) demande à Cord toutes les 5 minutes « le client a-t-il payé ? », les webhooks de Cord préviennent votre système au moment où l’événement se produit, par un POST HTTP signé vers votre serveur.

Cas d’usage courants :

• Provisionner automatiquement une licence logicielle lorsqu’un devis passe au statut paid.
• Envoyer un message interne dans Slack la première fois qu’un client consulte un devis (viewed).
• Déclencher le processus de facturation de votre ERP lorsque le CFDI est timbré.

Configurer un endpoint

1. Activez le Mode développeur dans Votre compte › Préférences — cela fait apparaître la pastille « Développeurs » dans le coin inférieur droit, visible dans toute l’application. Ouvrez-la d’un clic ou avec la touche W. Voir la visite complète dans Cord Workbench.
2. Ouvrez l’onglet Webhooks du panneau.
3. Cliquez sur Ajouter un endpoint — un assistant s’ouvre en plein écran.
4. Choisissez les événements que vous voulez recevoir : ils sont regroupés par famille, avec une recherche et une case par famille. Tous les événements (ou aucune case cochée) vous les envoie tous, y compris les types d’événements que Cord ajoutera à l’avenir. Voir le catalogue complet ci-dessous.
5. Saisissez votre URL — elle doit commencer par https:// ; dès la création, Cord refuse les destinations http://, localhost, les IP privées ou internes et les hôtes .internal/.local.
6. Conservez une copie de votre secret (whsec_…) — il ne s’affiche en clair qu’une seule fois. Ensuite, il n’apparaît que masqué. Depuis ce même écran, vous pouvez Envoyer un événement de test.

Le payload

Chaque envoi est un POST avec Content-Type: application/json et ce corps :

{
  "id": "evt_5f2a1c9e8b3d4a7f6e1c0d9b8a7f6e5c",
  "event": "quote.paid",
  "created_at": "2026-07-27T18:32:04.000Z",
  "data": {
    "id": "b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "folio": "COT-0148",
    "status": "paid",
    "moneda": "MXN",
    "total": 45200.00,
    "cliente": "Distribuidora El Zarco",
    "cliente_id": "9a1c3e5f-7b2d-4f6a-8c0e-1d3b5f7a9c2e",
    "link_publico": "https://cordhq.app/q/6f2a9c4e1b7d3f8a0c5e2b9d4f1a6c3e"
  }
}

id est l’identité de l’événement, et non celle du devis — elle reste la même d’une nouvelle tentative à l’autre et lors d’un renvoi manuel (voir identité de l’événement et idempotence). data.id est l’id interne du devis.

Signatures et sécurité

Cord signe chaque envoi avec deux en-têtes. Utilisez constructEvent de @flouviahq/node (voir le SDK Node) pour ne pas avoir à implémenter la vérification vous-même. Il exige X-Cord-Signature-V1 avec horodatage, compare en temps constant et rejette un envoi vieux de plus de 5 minutes :

import { constructEvent } from '@flouviahq/node';

const event = await constructEvent(
  await req.text(),
  req.headers,
  process.env.CORD_WEBHOOK_SECRET!,
);

Chaque envoi porte ces en-têtes :

Vérifier la signature manuellement

Si vous n’utilisez pas le SDK, voici l’algorithme complet. C’est ce que fait constructEvent :

1. Lisez le corps brut, exactement tel qu’il est arrivé. Un JSON parsé puis resérialisé ne correspondra pas.
2. Dans l’en-tête X-Cord-Signature-V1, prenez t et toutes les valeurs v1 (deux arrivent pendant un renouvellement).
3. Rejetez l’envoi si t s’écarte de plus de 300 secondes de votre horloge : c’est un rejeu.
4. Calculez HMAC-SHA256(secret, "<t>.<corps brut>") en hexadécimal.
5. Acceptez l’envoi s’il correspond à l’une des valeurs v1, en comparant en temps constant.

import { createHmac, timingSafeEqual } from 'node:crypto';

export function verifyCordSignature(rawBody, header, secret, toleranceSec = 300) {
  if (!header) return false;
  let t = null;
  const signatures = [];
  for (const part of header.split(',')) {
    const i = part.indexOf('=');
    if (i < 0) continue;
    const k = part.slice(0, i).trim();
    const v = part.slice(i + 1).trim();
    if (k === 't' && /^\d+$/.test(v)) t = Number(v);
    else if (k === 'v1' && /^[0-9a-f]{64}$/i.test(v)) signatures.push(Buffer.from(v, 'hex'));
  }
  if (t === null || signatures.length === 0) return false;
  if (Math.abs(Math.floor(Date.now() / 1000) - t) > toleranceSec) return false;
  const expected = createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest();
  return signatures.some((s) => s.length === expected.length && timingSafeEqual(s, expected));
}

Avec Express, demandez le corps brut uniquement sur cette route :

import express from 'express';
import { verifyCordSignature } from './verify-cord.js';

const app = express();

app.post('/webhooks/cord', express.raw({ type: 'application/json' }), (req, res) => {
  if (!verifyCordSignature(req.body, req.get('X-Cord-Signature-V1'), process.env.CORD_WEBHOOK_SECRET)) {
    return res.sendStatus(400);
  }
  const event = JSON.parse(req.body);
  // Dédupliquez par event.id avant d’appliquer des effets de bord.
  res.sendStatus(200);
});

app.listen(3000);

L’événement de test ping

Lorsque ping est sélectionné (l’option par défaut), le bouton Tester d’un endpoint dans le Workbench envoie un envoi avec event: "ping" par le même chemin qu’un événement réel (signature, en-têtes et journal). Il utilise des données d’exemple ayant la forme d’un devis, plus un champ mensaje. Tout test porte "test": true au premier niveau du payload :

{
  "id": "evt_0b7e3d9a1c5f2e8b4a6d0c9f3e1b7a5d",
  "event": "ping",
  "created_at": "2026-10-07T17:12:09.441Z",
  "test": true,
  "data": {
    "id": "00000000-0000-0000-0000-000000000000",
    "folio": "COT-PRUEBA",
    "status": "sent",
    "moneda": "MXN",
    "total": 12500,
    "cliente": "Cliente de prueba S.A. de C.V.",
    "cliente_id": null,
    "link_publico": "https://cordhq.app/q/demo",
    "mensaje": "Esta es una entrega de prueba enviada desde el Workbench de Cord."
  }
}

Au lieu de ping, vous pouvez choisir n’importe quel événement auquel l’endpoint est abonné : il arrive avec son type réel, des données d’exemple dans la version de l’API de l’endpoint et, lui aussi, "test": true. Un test n’est tenté qu’une seule fois : s’il échoue, il n’entre pas dans le calendrier des nouvelles tentatives. Les tests n’apparaissent pas dans l’historique des événements et ne déclenchent pas de Workflows. Répondez 2xx et ignorez-les. Pour tester avec l’un des 41 événements réels et les données d’un objet de test, utilisez le simulateur de webhooks ou cord trigger de la CLI.

Identité de l’événement et idempotence

Chaque événement logique a un id stable (evt_…), identique dans le corps et dans X-Cord-Event-Id/Idempotency-Key. C’est la même valeur :

• À chaque nouvelle tentative automatique d’un même événement (voir la section suivante).
• Lors d’un renvoi manuel depuis le Workbench (« Réessayer » dans le journal des envois) — le payload est renvoyé à l’octet près, id compris.

Comme les nouvelles tentatives et les renvois peuvent faire recevoir le même événement plusieurs fois à votre endpoint, votre handler doit être idempotent : enregistrez les id déjà traités (même dans une simple table avec une contrainte unique) et ignorez silencieusement les doublons avant d’appliquer des effets de bord (débiter une carte, envoyer un e-mail, etc.).

Nouvelles tentatives et envoi garanti

Cord met chaque événement en file d’attente avant de tenter de l’envoyer — si votre endpoint est indisponible, l’événement n’est pas perdu : il suit un calendrier de nouvelles tentatives avec backoff exponentiel, jusqu’à 11 tentatives sur environ 3,6 jours :

(Avec un jitter de ±20 %, pour que de nombreux endpoints tombés en même temps ne reçoivent pas la nouvelle tentative exactement à la même seconde.) Toute réponse autre que 2xx, une erreur réseau ou l’absence de réponse en 5 secondes compte comme un échec et programme la tentative suivante. Répondez vite et traitez ensuite : enregistrez l’événement et répondez 200 avant tout traitement lourd. Un 3xx (redirection) n’est jamais suivi — il est traité comme un échec ; si l’URL de votre endpoint a changé, mettez-la à jour dans le Workbench au lieu de laisser une redirection.

L’envoi se fait au moins une fois (at-least-once), et non exactement une fois — d’où l’importance de dédupliquer par id (voir plus haut).

Santé de l’endpoint

Cord surveille la série d’échecs de chaque endpoint (seuls comptent les événements qui ont épuisé leur calendrier de nouvelles tentatives, ou les échecs d’un test ou d’un renvoi manuel — jamais une tentative qui a encore des nouvelles tentatives devant elle) :

• 3 échecs consécutifs → vous recevez un e-mail d’avertissement (au maximum un toutes les 24 h).
• 5 échecs consécutifs → l’endpoint est désactivé automatiquement (il cesse de recevoir de nouveaux événements) et vous recevez un e-mail expliquant pourquoi. Les événements encore en attente de nouvelle tentative pour cet endpoint sont annulés — ils ne s’accumulent pas indéfiniment contre une destination indisponible.

Les deux e-mails sont adressés au propriétaire du compte, dans la langue de votre compte (Paramètres › Général).

Une fois votre endpoint réparé, vous pouvez, depuis l’onglet Webhooks du Workbench :

• Réactiver — recevoir à nouveau les nouveaux événements à partir de maintenant.
• Réactiver et réessayer — remettre en plus en file d’attente ce qui a échoué au cours des dernières 24 heures (jamais tout l’arriéré, pour ne pas vous submerger d’anciens événements d’un coup).

Renouvellement du secret

Vous pouvez renouveler le secret d’un endpoint sans perdre un seul envoi. Dans le Workbench, cliquez sur « Renouveler le secret », choisissez une période de chevauchement (1 h / 24 h / 72 h) et confirmez — le nouveau secret s’affiche en clair une seule fois.

Pendant cette période, Cord signe chaque envoi avec les deux secrets à la fois :

X-Cord-Signature-V1: t=1732650000,v1=<hmac avec le NOUVEAU secret>,v1=<hmac avec l’ANCIEN secret>

L’ordre est fixe : le v1= du nouveau secret vient en premier et celui de l’ancien secret en dernier. Vous pouvez ainsi mettre à jour votre CORD_WEBHOOK_SECRET à tout moment pendant la période sans qu’aucun envoi ne soit rejeté, à condition que votre vérification compare toutes les valeurs v1= de l’en-tête. Le SDK accepte déjà celle des deux qui correspond. Si vous vérifiez manuellement, ne conservez pas une seule valeur : lire uniquement la première suppose que vous ayez déjà le nouveau secret, et un parser qui conserve le dernier v1= (par exemple, un parser qui construit une table clé-valeur) ne valide qu’avec l’ancien secret pendant la période ; il échoue donc dès que vous passez au nouveau avant la fin de la période.

La signature historique X-Cord-Signature n’accepte qu’une seule valeur : pendant la période, elle est donc calculée avec l’ancien secret ; une fois la période terminée, elle est signée avec le nouveau. À la fin de la période, Cord cesse de signer avec l’ancien secret dans les deux en-têtes.

Catalogue des événements

Les événements de litiges, de remboursements et de versements contiennent referencia, l’identifiant de l’opération chez le prestataire de paiement, et ne sont émis qu’une fois par opération et par issue. Lorsque le paiement provient d’un devis, ils contiennent aussi cotizacion_id, folio et cliente.

Remarque : payment.partial contient dans data des champs supplémentaires que les autres événements de devis n’ont pas : tipo (anticipo|saldo|cuota), monto, numero_cuota, saldo_pendiente et payment_method, en plus du résumé habituel du devis (numéro, client, total, lien).

{
  "id": "evt_7c3e9a1f5b2d8e4a0c6f3b9d1e7a5c2f",
  "event": "invoice.paid",
  "created_at": "2026-08-20T14:00:00.000Z",
  "data": {
    "id": "d4a1b3c5-7e9f-4a2b-8c4d-6e8f0a2b4c6d",
    "object": "invoice",
    "numero": "FAC-0032",
    "folio_fiscal": "3F2A9C1E-7B4D-4E6A-8C2F-1D5B9E3A7C40",
    "estado": "paid",
    "estado_fiscal": "issued",
    "pais": "MX",
    "tipo": "cfdi_40",
    "moneda": "MXN",
    "total": 12500.00,
    "pagado": 12500.00,
    "saldo": 0,
    "vence": "2026-08-30",
    "cliente": "Distribuidora El Zarco",
    "cotizacion_id": null,
    "link_publico": "https://cordhq.app/i/9c1f4e7a2b5d8c0f3a6e9b2d5f8a1c4e"
  }
}

Forme de data pour les clients, produits, tâches et promesses

Chaque objet contient object pour que vous puissiez les distinguer. L’événement de produit n’inclut jamais le coût ni la marge.

Gérer les endpoints via l’API

Des plateformes comme Zapier ou Make créent et suppriment elles-mêmes leurs abonnements. Ces routes existent pour cela :

Les mêmes règles d’URL que dans le Workbench s’appliquent : uniquement https:// vers des hôtes publics. Ces abonnements ne sont pas décomptés des endpoints de votre équipe : ils disposent de leur propre quota de 100 par organisation (integration_limit_reached).

Historique des événements via l’API

Si votre système a été indisponible plus longtemps que ne le couvrent les nouvelles tentatives, ou si vous préférez interroger plutôt que recevoir, GET /api/v1/events (portée read) renvoie les événements de votre organisation du plus récent au plus ancien, qu’un endpoint y soit abonné ou non :

curl "https://cordhq.app/api/v1/events?type=quote.approved&limit=50" \
     -H "Authorization: Bearer sk_live_tU..."

{
  "data": [
    {
      "id": "6b0e2f4a-8c1d-4e3b-9a5f-7d2c0e8b1a46",
      "type": "quote.approved",
      "object": "quote",
      "object_id": "b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "data": { "id": "b3f1c2d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "folio": "COT-0148", "status": "approved", "moneda": "MXN", "total": 45200 },
      "actor": "client",
      "created_at": "2026-09-14T18:32:04.123Z"
    }
  ],
  "meta": { "next_cursor": "MjAyNi0wOS0xNFQxODozMjowNC4xMjMwMDBafDZiMGUyZjRhLThjMWQtNGUzYi05YTVmLTdkMmMwZThiMWE0Ng" }
}

• Filtres facultatifs : type (un événement du catalogue) et object_id.
• next_cursor est un jeton opaque : répétez la requête avec ?cursor=<next_cursor>. Il vaut null lorsqu’il n’y a plus de pages.
• actor indique qui a provoqué l’événement : user:<id>, api:<clé>, mcp:<clé>, client (le client sur le lien public), workflow:<id>, system et d’autres. Voir la liste complète.
• L’id de l’historique est l’UUID de l’enregistrement, différent de l’evt_… du webhook.
• Contrairement au webhook, data n’inclut pas link_publico : le lien est un identifiant d’accès et n’est pas conservé dans l’historique.

Journal des envois et conservation

Dans l’onglet Webhooks du Workbench, chaque endpoint dispose d’un journal dépliable avec ses 50 derniers envois (événement, tentative, statut, durée et date). Chacun s’ouvre pour afficher ce que Cord a envoyé (le payload exact), ce que votre serveur a répondu et le bouton Réessayer. L’onglet Événements du Workbench montre la même chose sous un autre angle : un événement logique avec son envoi vers chaque endpoint, au lieu d’un journal par endpoint, et le bouton Renvoyer. Le journal est conservé 30 jours ; les événements dont l’envoi a définitivement échoué sont conservés 90 jours (pour que « Réessayer » continue de fonctionner plus longtemps dans ce cas). N’utilisez pas le journal de Cord comme stockage à long terme de ce qui a été envoyé — conservez vous-même dans votre propre système ce dont vous avez besoin au moment du traitement.