Kann ich einen externen Webhook (für Salesforce) anbinden?

    Ja, das geht. Bei jeder neuen oder geänderten Spende kann twingle einen externen Webhook aufrufen. Dieser enthält alle Daten der Spende und kann optional mit einem Sicherheitshash versehen werden um den Versand durch twingle zu verifizieren.
    Der Webhook kann verwendet werden um externe Systeme, wie zum Beispiel Salesforce, oder auch andere CRM Systeme anzubinden. Eventuell ist es nötig, eine Middleware (Zapier o.ä.) dazwischen zu schalten.

    Einrichtung

    Zur Einrichtung sind zwei Schritte nötig:

    1. Logge dich im twingleMANAGER ein und öffne Organisationseinstellungen / Allgemein. Aktiviere im Bereich "CRM: Salesforce / Webhook" die Option "Webhook konfigurieren" und trage die "URL des Webhooks" ein.

    • Optional: Trage bei "Secret für den Validierungshash" ein Secret ein.
    • Optional: Wähle bei "Verzögerte Übermittlung neuer Zahlungen" eine Verzögerung von 3, 5, 10, 15, 20 oder 30 Minuten. Standard ist "keine Verzögerung". Das ist hilfreich, wenn Spender:innen nach der Zahlung noch Zeit brauchen, ihre Daten einzugeben.
    2. Öffne die Projekteinstellungen / Kontaktdaten & Einbindung und aktiviere im Bereich "CRM: Salesforce / Webhook" die Option "Neue und geänderte Spenden an Webhook übertragen". Wiederhole das für jedes Projekt, dessen Zahlungen übertragen werden sollen. Der Bereich erscheint im Projekt erst, wenn der Webhook in den Organisationseinstellungen aktiviert ist.

    Hinweise:

    • von Projekten die nicht aktiviert worden sind, werden keine Daten an den Webhook übertragen
    • Historische Daten, also Transaktionen die zeitlich vor der Aktivierung liegen, werden nicht übertragen

    Nutzung

    Die Daten einer Transaktion werden immer direkt im Anschluss (oder nach gewählter Verzögerung) übertragen. Der Umfang und die Struktur der Daten ist in einem extra Artikel beschrieben. Die Daten werden im JSON-Format im body eines POST-Requests übertragen.
    Der Datenumfang ist bei einer neuen Transaktion der Gleiche wie bei einer geänderten Transaktion. Ob es sich um ein Update handelt, ist im Header des Requests zu sehen. Dort wird der Wert X-Twingle-Isupdate auf 1 gesetzt, wenn es ein Update ist, sonst ist der Wert immer 0.

    Sollte in der Konfiguration ein Secret hinterlegt sein, dann wird dieses benutzt, um für die gesamte Payload des Requests einen Hashwert zu erzeugen und diesen im Header im Feld X-Hub-Signature-256 zu übertragen, in der Form sha256=<Hashwert>. Der Hashwert ist ein sha256-Hash.

    Pro Organisation kann eine Webhook-URL hinterlegt werden. Sollen mehrere Systeme die Daten erhalten oder ist keine direkte Anbindung möglich, nutze eine Middleware wie Zapier, make.com oder n8n: Lege dort einen eingehenden Webhook an und trage dessen URL im twingleMANAGER ein.

    Zahlungsarten und IDs im Webhook

    Das Feld payment_method enthält die Zahlungsart. Apple Pay und Google Pay kommen immer als applepay bzw. googlepay, egal über welchen Zahlungsdienstleister sie laufen. PayPal-Zahlungen kommen als paypal, Kartenzahlungen über PayPal als creditcard. Lastschrift (automatisch) kommt als debit_automatic, Lastschrift (manuell) als debit. Alle möglichen Werte stehen in Documentation for webhook payload.

    Diese IDs kommen mit:
    • trx_id und transaction_guid: die eindeutige ID der Zahlung in twingle
    • parent_trx_id und parent_transaction_guid: bei wiederkehrenden Zahlungen die ID der ersten Zahlung der Serie
    • payout_reference: die Referenz der Auszahlung, sobald twingle sie kennt. Bei PayPal ist das die PayPal-Transaktions-ID, bei Kartenzahlungen und Stripe die Auszahlungsreferenz
    • paypal_payer_email: die E-Mail-Adresse des PayPal-Kontos, nur bei PayPal

    Antwort des Empfängers und mehrfache Übertragung

    Dein System sollte mit dem HTTP-Status 200, 201 oder 202 antworten. Andere Status-Codes wertet twingle als Fehler.

    Eine Zahlung kann mehrmals an den Webhook gesendet werden, nämlich bei jedem Update. Das passiert zum Beispiel, wenn Kontaktdaten nach der Zahlung ergänzt werden oder wenn einige Tage später, in der Regel gegen 18 Uhr, die Buchungsdaten an die Bank übermittelt werden. Das gilt für alle Zahlungsarten. Erkenne wiederholte Übertragungen an der trx_id und am Header X-Twingle-Isupdate, und lege die Zahlung in deinem System nicht doppelt an, sondern aktualisiere sie.

    Authentifizierung

    Benötigt dein Webhook eine Authentifizierung, wähle bei "Authentifizierung" zwischen Basic Auth und OAuth:
    1. Basic Auth: Trage Login und Passwort ein, twingle sendet sie bei jedem Aufruf im Header Authorization.
    2. OAuth: Trage Token-URL, Client-ID und Client-Secret ein. twingle holt vor jedem Aufruf ein Access-Token von der Token-URL und sendet es im Header Authorization als Bearer-Token an den Webhook.

    Alternative: twingleAPI

    Wenn du Daten nicht nach jeder Zahlung empfangen, sondern abrufen möchtest, kannst du die twingleAPI nutzen. Mehr dazu steht in API-Nutzung und Entwickler-Zugriff.
    Veröffentlicht:
    Documentation for webhook payload
    Typische Fehler bei der CiviCRM Anbindung