Webhooks einrichten und prüfen

Webhooks sind HTTP-Aufrufe (Callbacks), die unser Server asynchron an Ihren sendet, wenn ein wichtiges Ereignis eintritt (z. B. wenn ein Angebot bestätigt oder bezahlt wurde).

Endpoint registrieren

Um Webhooks zu empfangen, stellen Sie auf Ihrem Server eine POST-Route bereit (z. B. https://api.ihrunternehmen.de/webhooks/cord).

1. Aktivieren Sie den Entwicklermodus unter Ihr Konto › Präferenzen. Unten rechts erscheint die Schaltfläche Entwickler: Öffnen Sie sie (oder drücken Sie W) und wechseln Sie in den Tab Webhooks der Workbench (/app?wb=webhooks).
2. Klicken Sie auf Endpoint hinzufügen und wählen Sie die Ereignisse: Alle Ereignisse, eine ganze Gruppe oder einzelne Ereignisse. Die Suche filtert die 42 Ereignisse nach Namen.
3. Geben Sie Ihre URL ein, öffentlich und mit HTTPS, und klicken Sie auf Endpoint erstellen. Das Signatur-Secret wird nur ein einziges Mal angezeigt: Bewahren Sie es auf.

Verfügbare Ereignisse

Cord sendet Ereignisse zum Lebenszyklus des Angebots und, getrennt davon, zur Rechnung als eigenständigem Objekt (siehe Rechnungsstellung und die API):

• quote.sent – an den Kunden gesendet.
• quote.viewed – der Kunde hat es geöffnet.
• quote.approved – der Kunde hat es bestätigt.
• quote.rejected – der Kunde hat es abgelehnt.
• quote.updated – es wurde geändert und erneut gesendet.
• quote.expired – es ist ohne Antwort abgelaufen.
• quote.deleted – ein Entwurf wurde gelöscht.
• quote.paid – es wurde vollständig bezahlt.
• payment.partial – eine Anzahlung, ein Restbetrag, eine Rate oder eine Zahlung eines Meilensteinplans ist eingegangen, ohne den Gesamtbetrag zu decken.
• quote.milestone_completed – Sie haben eine Zahlung eines Zahlungsplans nach Meilensteinen als erreicht markiert; ab dann kann der Kunde sie bezahlen.
• payment.failed – eine wiederkehrende Zahlung ist fehlgeschlagen.
• invoice.issued, invoice.stamped – die Rechnung zu einem Angebot wurde ausgestellt: eine Rechnung ohne Behördenmeldung außerhalb Mexikos oder ein gestempeltes CFDI.
• invoice.finalized, invoice.sent, invoice.paid, invoice.payment_failed, invoice.voided, invoice.marked_uncollectible, invoice.overdue – Lebenszyklus einer Rechnung, die als eigene Ressource über /api/v1/facturas erstellt wurde.
• quote.created, quote.approval_requested, quote.approval_decided, quote.comment_added – ein Angebot wurde erstellt, eine interne Freigabe wurde angefordert oder entschieden, oder jemand hat in der Konversation geschrieben.
• client.created, client.updated, client.deleted, product.created, product.updated, product.deleted – Änderungen in Ihrem Kundenverzeichnis und Ihrem Katalog.
• task.created, task.completed, promise.created, promise.kept, promise.broken – Aufgaben und Zahlungszusagen.
• dispute.created, dispute.closed, refund.succeeded, refund.failed, payout.paid, payout.failed, account.updated – Rückbuchungen, Rückerstattungen, Auszahlungen und Änderungen an Ihrem Zahlungskonto.

Mit Alle Ereignisse erhält der Endpoint auch die Ereignisse, die Cord später hinzufügt.

Der Body ist JSON: { "id": "evt_...", "event": "quote.paid", "created_at": "...", "data": { "id", "folio", "status", "moneda", "total", "cliente", "cliente_id", "link_publico" } }. Die id des Ereignisses bleibt über Wiederholungen und ein manuelles erneutes Senden aus der Workbench hinweg gleich – verwenden Sie sie, um auf Ihrem Server Duplikate zu erkennen.

Signaturprüfung

Prüfen Sie immer die Signatur, um sicherzustellen, dass das Ereignis von Cord stammt. Jede Zustellung enthält X-Cord-Signature-V1 (mit Zeitstempel als Schutz vor Wiederholungsangriffen) und aus Kompatibilitätsgründen die ältere Signatur X-Cord-Signature (ohne Zeitstempel). Der Name des Ereignisses steht in X-Cord-Event und seine stabile ID in X-Cord-Event-Id/Idempotency-Key. Mit Node prüft constructEvent aus @flouviahq/node die Signatur für Sie; wenn Sie sie lieber selbst in einer beliebigen Sprache prüfen möchten, sehen Sie sich den Prüfcode an.

Wiederholungen und Prüfung

Die Schaltfläche Testen jedes Endpoints sendet eine Testzustellung: ping oder ein beliebiges abonniertes Ereignis, mit Beispieldaten und "test": true auf oberster Ebene des Bodys.

Wenn Sie einen Endpoint aufklappen, sehen Sie sein Zustellprotokoll (Status, Latenz und Antwort jedes Versuchs), und wenn Sie eine Zustellung öffnen, sehen Sie, was Cord gesendet und was Ihr Server geantwortet hat. Schlägt eine Zustellung fehl, wiederholen Sie sie von dort aus oder senden das Ereignis im Tab Ereignisse erneut. Zustellverlauf, Wiederholen und erneutes Senden sind ab dem Professional-Tarif enthalten.