Webhooks

Warum Webhooks?

Statt dass Ihr System (ein ERP, ein Ablauf in Zapier/Make oder Ihr eigenes Backend) Cord alle 5 Minuten fragt, ob der Kunde schon bezahlt hat, benachrichtigen die Webhooks von Cord Ihr System in dem Moment, in dem das Ereignis eintritt, mit einem signierten HTTP-POST an Ihren Server.

Häufige Anwendungsfälle:

• Automatisch eine Softwarelizenz bereitstellen, wenn ein Angebot den Status paid erreicht.
• Eine interne Nachricht in Slack senden, wenn der Kunde ein Angebot zum ersten Mal ansieht (viewed).
• Den Abrechnungsprozess in Ihrem ERP auslösen, wenn der CFDI gestempelt wird.

Einen Endpoint einrichten

1. Aktivieren Sie den Entwicklermodus unter Ihr Konto › Präferenzen – dadurch erscheint die Schaltfläche „Entwickler“ unten rechts, in der gesamten App sichtbar. Öffnen Sie sie per Klick oder mit der Taste W. Die vollständige Tour finden Sie unter Cord Workbench.
2. Öffnen Sie den Tab Webhooks des Panels.
3. Klicken Sie auf Endpoint hinzufügen – es öffnet sich ein Assistent im Vollbild.
4. Wählen Sie die Ereignisse, die Sie empfangen möchten: Sie sind nach Familien gruppiert, mit Suche und einem Kontrollkästchen pro Familie. Alle Ereignisse (oder gar keine Auswahl) sendet Ihnen alle, auch Ereignistypen, die Cord künftig hinzufügt. Siehe den vollständigen Katalog weiter unten.
5. Geben Sie Ihre URL ein – sie muss mit https:// beginnen; Cord lehnt bereits beim Anlegen Ziele mit http://, localhost, privaten/internen IP-Adressen und Hosts .internal/.local ab.
6. Bewahren Sie eine Kopie Ihres Secrets (whsec_…) auf – es wird nur einmal im Klartext angezeigt. Danach ist es nur noch maskiert sichtbar. Auf derselben Seite können Sie Testereignis senden.

Der Payload

Jede Zustellung ist ein POST mit Content-Type: application/json und diesem Body:

{
  "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 ist die Identität des Ereignisses, nicht des Angebots – derselbe Wert bei Wiederholungen und bei einem manuellen Replay (siehe Identität des Ereignisses und Idempotenz). data.id ist die interne ID des Angebots.

Signaturen und Sicherheit

Cord signiert jede Zustellung mit zwei Headern. Verwenden Sie constructEvent aus @flouviahq/node (siehe das Node-SDK), damit Sie die Verifizierung nicht selbst implementieren müssen. Die Funktion verlangt X-Cord-Signature-V1 mit Zeitstempel, vergleicht in konstanter Zeit und lehnt eine Zustellung ab, die älter als 5 Minuten ist:

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

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

Jede Zustellung trägt diese Header:

Signatur von Hand prüfen

Wenn Sie das SDK nicht verwenden, ist dies der vollständige Algorithmus. Er entspricht dem, was constructEvent tut:

1. Lesen Sie den rohen Body, genau so, wie er angekommen ist. Geparstes und wieder serialisiertes JSON passt nicht.
2. Entnehmen Sie dem Header X-Cord-Signature-V1 den Wert t und alle v1-Werte (während einer Rotation kommen zwei an).
3. Lehnen Sie die Zustellung ab, wenn t mehr als 300 Sekunden von Ihrer Uhrzeit abweicht: Es handelt sich um einen Replay.
4. Berechnen Sie HMAC-SHA256(secret, "<t>.<roher Body>") in Hexadezimal.
5. Akzeptieren Sie, wenn das Ergebnis mit einem beliebigen der v1-Werte übereinstimmt, und vergleichen Sie dabei in konstanter Zeit.

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

Mit Express fordern Sie den rohen Body nur auf dieser Route an:

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);
  // Vor jedem Nebeneffekt nach event.id deduplizieren.
  res.sendStatus(200);
});

app.listen(3000);

Das Testereignis ping

Die Schaltfläche Testen eines Endpoints in der Workbench sendet bei ausgewähltem ping (die Standardoption) eine Zustellung mit event: "ping" über denselben Weg wie ein echtes Ereignis (Signatur, Header und Protokoll). Sie verwendet Beispieldaten in der Form eines Angebots und ein Feld mensaje. Jeder Test trägt "test": true auf der obersten Ebene des Payloads:

{
  "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."
  }
}

Statt ping können Sie jedes Ereignis wählen, das der Endpoint abonniert hat: Es kommt mit seinem echten Typ an, mit Beispieldaten in der API-Version des Endpoints und ebenfalls mit "test": true. Ein Test wird nur einmal versucht: Schlägt er fehl, kommt er nicht in den Wiederholungsplan. Tests erscheinen nicht im Ereignisverlauf und lösen keine Workflows aus. Antworten Sie mit 2xx und verwerfen Sie sie. Um mit einem der 41 echten Ereignisse und den Daten eines Testobjekts zu testen, verwenden Sie den Webhook-Simulator oder cord trigger aus der CLI.

Identität des Ereignisses und Idempotenz

Jedes logische Ereignis hat eine stabile id (evt_…), identisch im Body und in X-Cord-Event-Id/Idempotency-Key. Es ist derselbe Wert:

• Bei jeder automatischen Wiederholung desselben Ereignisses (siehe nächster Abschnitt).
• Bei einem manuellen Replay aus der Workbench („Erneut versuchen“ im Zustellprotokoll) – der Payload wird Byte für Byte identisch erneut gesendet, einschließlich der id.

Da Wiederholungen und Replays dazu führen können, dass Ihr Endpoint dasselbe Ereignis mehr als einmal erhält, muss Ihr Handler idempotent sein: Speichern Sie die bereits verarbeiteten id (und sei es in einer einfachen Tabelle mit unique) und verwerfen Sie Wiederholungen stillschweigend, bevor Sie Nebeneffekte ausführen (eine Zahlung einziehen, eine E-Mail senden usw.).

Wiederholungen und garantierte Zustellung

Cord stellt jedes Ereignis vor dem ersten Zustellversuch in eine Warteschlange – ist Ihr Endpoint nicht erreichbar, geht das Ereignis nicht verloren: Es folgt einem Wiederholungsplan mit exponentiellem Backoff von bis zu 11 Versuchen über ca. 3,6 Tage:

(Mit einem Jitter von ±20 %, damit viele gleichzeitig ausgefallene Endpoints die Wiederholung nicht exakt in derselben Sekunde erhalten.) Jede Antwort außer 2xx, ein Netzwerkfehler oder keine Antwort innerhalb von 5 Sekunden gilt als Fehlschlag und plant den nächsten Versuch. Antworten Sie schnell und verarbeiten Sie später: Speichern Sie das Ereignis und antworten Sie mit 200, bevor Sie aufwendige Arbeit erledigen. Einem 3xx (Weiterleitung) wird nie gefolgt – es gilt als Fehlschlag; hat sich die URL Ihres Endpoints geändert, aktualisieren Sie sie in der Workbench, statt eine Weiterleitung einzurichten.

Die Zustellung erfolgt mindestens einmal (at-least-once), nicht genau einmal – deshalb ist die Deduplizierung nach id so wichtig (siehe oben).

Zustand des Endpoints

Cord überwacht die Serie von Fehlschlägen jedes Endpoints (gezählt werden nur Ereignisse, die ihren Wiederholungsplan ausgeschöpft haben, oder fehlgeschlagene manuelle Tests/Replays – nie ein Versuch, dem noch Wiederholungen bevorstehen):

• 3 Fehlschläge in Folge → Sie erhalten eine Warn-E-Mail (höchstens eine alle 24 h).
• 5 Fehlschläge in Folge → der Endpoint wird automatisch deaktiviert (er erhält keine neuen Ereignisse mehr), und Sie erhalten eine E-Mail mit der Begründung. Ereignisse, die für diesen Endpoint noch auf eine Wiederholung warteten, werden abgebrochen – sie stauen sich nicht endlos gegen ein nicht erreichbares Ziel.

Beide E-Mails gehen an den Inhaber des Kontos, in der Sprache Ihres Kontos (Einstellungen › Allgemein).

Sobald Sie Ihren Endpoint repariert haben, können Sie im Tab Webhooks der Workbench:

• Reaktivieren – ab sofort wieder neue Ereignisse empfangen.
• Reaktivieren und wiederholen – zusätzlich wird erneut eingereiht, was in den letzten 24 Stunden fehlgeschlagen ist (nie der gesamte Rückstand, damit Sie nicht auf einen Schlag mit alten Ereignissen überflutet werden).

Secret-Rotation

Sie können das Secret eines Endpoints rotieren, ohne eine einzige Zustellung zu verlieren. Klicken Sie in der Workbench auf „Secret rotieren“, wählen Sie ein Überlappungsfenster (1 h / 24 h / 72 h) und bestätigen Sie – Sie sehen das neue Secret einmalig im Klartext.

Während des Fensters signiert Cord jede Zustellung gleichzeitig mit beiden Secrets:

X-Cord-Signature-V1: t=1732650000,v1=<hmac with the NEW secret>,v1=<hmac with the OLD secret>

Die Reihenfolge ist fest: Das v1= des neuen Secrets steht zuerst, das des alten am Ende. So können Sie Ihr CORD_WEBHOOK_SECRET zu jedem Zeitpunkt innerhalb des Fensters aktualisieren, ohne dass eine Zustellung abgelehnt wird – vorausgesetzt, Ihre Verifizierung vergleicht alle v1= im Header. Das SDK akzeptiert bereits jedes der beiden, das passt. Wenn Sie von Hand verifizieren, behalten Sie nicht nur einen einzigen Wert: Wer nur den ersten liest, muss das neue Secret bereits haben, und ein Parser, der das letzte v1= behält (zum Beispiel einer, der eine Schlüssel-Wert-Map aufbaut), validiert während des Fensters nur mit dem alten Secret und schlägt daher fehl, sobald Sie vor Ende des Fensters auf das neue wechseln.

Die Legacy-Signatur X-Cord-Signature fasst nur einen Wert, daher wird sie während des Fensters mit dem alten Secret berechnet; nach dem Ende des Fensters wird sie mit dem neuen signiert. Sobald das Fenster endet, signiert Cord in beiden Headern nicht mehr mit dem alten Secret.

Ereigniskatalog

Die Ereignisse zu Rückbuchungen, Rückerstattungen und Auszahlungen enthalten referencia, die Kennung des Vorgangs beim Zahlungsdienstleister, und werden pro Vorgang und Ergebnis nur einmal gesendet. Stammt die Zahlung aus einem Angebot, enthalten sie außerdem cotizacion_id, folio und cliente.

Hinweis: payment.partial enthält in data zusätzliche Felder, die die übrigen Angebots-Ereignisse nicht haben: tipo (anticipo|saldo|cuota), monto, numero_cuota, saldo_pendiente und payment_method, zusätzlich zur normalen Zusammenfassung des Angebots (Nummer, Kunde, Gesamtbetrag, Link).

{
  "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"
  }
}

Form von data bei Kunden, Produkten, Aufgaben und Zahlungszusagen

Jedes Objekt enthält object, damit Sie es unterscheiden können. Das Produktereignis enthält nie Kosten oder Marge.

Endpoints über die API verwalten

Plattformen wie Zapier oder Make erstellen und löschen ihre Abonnements selbst. Dafür gibt es diese Routen:

Es gelten dieselben URL-Regeln wie in der Workbench: nur https:// zu öffentlichen Hosts. Diese Abonnements zählen nicht gegen die Endpoints Ihres Teams: Sie haben ein eigenes Kontingent von 100 pro Organisation (integration_limit_reached).

Ereignisverlauf über die API

War Ihr System länger nicht erreichbar, als die Wiederholungen abdecken, oder fragen Sie lieber ab, statt zu empfangen, gibt GET /api/v1/events (Scope read) die Ereignisse Ihrer Organisation vom neuesten zum ältesten zurück, unabhängig davon, ob Endpoints abonniert sind:

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" }
}

• Optionale Filter: type (ein Ereignis aus dem Katalog) und object_id.
• next_cursor ist ein undurchsichtiges Token: Wiederholen Sie die Anfrage mit ?cursor=<next_cursor>. Es ist null, wenn es keine weiteren Seiten gibt.
• actor gibt an, wer das Ereignis ausgelöst hat: user:<id>, api:<key>, mcp:<key>, client (der Kunde im öffentlichen Link), workflow:<id>, system und weitere. Siehe die vollständige Liste.
• Die id im Verlauf ist die UUID des Datensatzes, nicht dasselbe wie das evt_… des Webhooks.
• Anders als beim Webhook enthält data kein link_publico: Der Link ist ein Zugangsnachweis und wird nicht im Verlauf gespeichert.

Zustellprotokoll und Aufbewahrung

Im Tab Webhooks der Workbench hat jeder Endpoint ein aufklappbares Protokoll mit seinen letzten 50 Zustellungen (Ereignis, Versuch, Status, Dauer und Datum). Jede lässt sich öffnen und zeigt, was Cord gesendet hat (den exakten Payload), was Ihr Server geantwortet hat und die Schaltfläche Erneut versuchen. Der Tab Ereignisse der Workbench zeigt dasselbe aus einem anderen Blickwinkel: ein logisches Ereignis mit seiner Zustellung an jeden Endpoint statt eines Protokolls pro Endpoint, und die Schaltfläche Erneut senden. Das Protokoll wird 30 Tage aufbewahrt; endgültig fehlgeschlagene Ereignisse 90 Tage (damit „Erneut versuchen“ in diesem Fall länger funktioniert). Nutzen Sie das Protokoll von Cord nicht als Langzeitspeicher für Gesendetes – speichern Sie, was Sie aufbewahren müssen, bei der Verarbeitung in Ihrem eigenen System.