Auf dieser Seite
Wo du das findest
Unter Studio → Automatisierungen → Integrationen liegen vier Bereiche: die Karte „Mit n8n, Make oder Zapier verbinden“, die Apps (fertige Verbindungen zu Google Sheets, HubSpot, SMS und mehr, siehe „Automatisierungen: Apps verbinden“), die Ereignis-Webhooks und die Zugangsdaten. Den Auslöser „Webhook empfangen“ richtest du direkt in der Automatisierung ein, die er starten soll.
Mit n8n, Make oder Zapier verbinden
Die Karte zeigt drei Wege, je nach Richtung, jeweils mit Beispielen zum Kopieren:
- Daten an BirdBuild senden: Eine Automatisierung mit dem Auslöser „Webhook empfangen“ hat eine eigene Adresse, jeder Aufruf startet den Ablauf. In n8n nimmst du dafür den Knoten „HTTP Request“, in Make das Modul „HTTP › Make a request“, in Zapier „Webhooks by Zapier › POST“.
- Ereignisse empfangen: BirdBuild meldet ausgewählte Ereignisse, etwa „Bestellung bezahlt“, signiert an deine Adresse. Dafür brauchst du in n8n einen Webhook-Knoten (POST), in Make „Webhooks › Custom webhook“, in Zapier „Webhooks by Zapier › Catch Hook“. Die Adresse trägst du als Ereignis-Webhook ein.
- BirdBuild steuern: Mit einem API-Token liest und ändert ein Dienst über die Schnittstelle Kontakte, Bestellungen, Termine und mehr. KI-Agenten verbinden sich über die MCP-Adresse, in n8n mit dem „MCP Client Tool“. API-Tokens legt der Kontoinhaber unter Einstellungen → API & Zugangsdaten an.
Über „n8n-Beispiel herunterladen“ bekommst du einen fertigen n8n-Ablauf, der ein BirdBuild-Ereignis empfängt und die Signatur ohne eigenen Code prüft. Er enthält keine echten Daten: Den geheimen Schlüssel trägst du im Knoten „Signatur berechnen“ ein.
Auslöser „Webhook empfangen“
Mit diesem Auslöser startet ein anderer Dienst deinen Ablauf. Die Adresse endet auf /server/hooks/a/ und einen langen Zufallsschlüssel. Sie entsteht beim Speichern; fehlt sie noch, erzeugst du sie mit „Jetzt erzeugen“. Aufrufe gehen per POST, PUT, PATCH oder GET. „Neue Adresse erzeugen“ ersetzt die Adresse nach einer Rückfrage, die bisherige funktioniert danach nicht mehr.
Angenommen werden JSON, Formulardaten (bei multipart nur die Textfelder) und reiner Text bis 64 KB. Im Ablauf stehen die Daten als {{trigger.body.…}} bereit, dazu trigger.query, trigger.headers, trigger.method und trigger.receivedAt. Anmelde-Header, Cookies und IP-Adressen speichert BirdBuild nicht. Gestartet wird nur, solange die Automatisierung aktiv ist.
Webhook absichern
Unter „Absicherung“ wählst du, wie BirdBuild einen Aufruf prüft:
- Ohne: Jeder, der die Adresse kennt, kann den Ablauf starten.
- Geheimer Schlüssel im Header: Der Aufruf schickt den geheimen Schlüssel im Header
X-BirdBuild-Secretmit. Das ist in n8n, Make und Zapier der einfachste Weg. - Signatur (HMAC): Der Aufruf schickt
X-BirdBuild-Timestamp(Unix-Zeit in Sekunden) undX-BirdBuild-Signature: sha256=…, den HMAC-SHA256 mit dem geheimen Schlüssel über Zeitstempel, einen Punkt und den Body. Ohne Body, etwa bei GET, wird der Query-Teil ohne „?“ signiert. Der Zeitstempel darf höchstens 5 Minuten abweichen. In n8n braucht das einen Crypto-Knoten davor.
Den geheimen Schlüssel siehst du nur einmal direkt nach dem Erzeugen, danach nur noch seine letzten Zeichen. Solange keiner erzeugt ist, lehnt BirdBuild Aufrufe mit Schlüssel oder Signatur ab. „Neuen Schlüssel erzeugen“ ersetzt ihn; Aufrufe mit dem bisherigen werden danach abgelehnt. Unter „Beispielaufruf“ stehen ein fertiger Aufruf für das Terminal und ein n8n-Knoten „HTTP Request“ zum Einfügen.
Testereignis und Kontakt aus dem Aufruf
„Auf Testereignis warten“ merkt sich 3 Minuten lang den nächsten Aufruf. Das geht auch im Entwurf, dort startet der Aufruf nichts. BirdBuild zeigt die empfangenen Daten als Baum; danach stehen ihre Felder im Button „Daten“ zum Anklicken bereit, und der Testlauf nutzt sie als Auslöser-Daten.
Unter „Kontakt aus dem Aufruf“ ordnest du E-Mail, Vorname und Nachname zu, dazu Telefon, Firma, Tags (mit Komma getrennt) und eine Liste. Als Wert nimmst du einen Platzhalter wie {{trigger.body.email}} oder einfach den Pfad body.email. Mit gültiger E-Mail legt BirdBuild den Kontakt an oder ergänzt ihn, ohne vorhandene Angaben zu überschreiben; Tags und Liste kommen dazu, als Quelle steht „Webhook“. Ohne E-Mail läuft der Ablauf ohne Kontakt.
Antworten und Grenzen
Ein angenommener Aufruf bekommt 202 mit der Lauf-ID zurück. Weitere Antworten: 404 (Adresse unbekannt oder Automatisierung nicht aktiv), 401 (Schlüssel oder Signatur passt nicht), 400 (ungültiges JSON), 413 (über 64 KB), 429 (zu viele Aufrufe) und 503 (Wartung). Je Auslöser gehen 120 Aufrufe pro Minute, je IP-Adresse 600 pro Minute und je Konto 20.000 am Tag.
Ereignis-Webhooks
Ein Ereignis-Webhook meldet Ereignisse aus deinem Projekt an eine Adresse deiner Wahl, etwa an n8n. Du gibst einen Namen, die Adresse (https://…) und die Ereignisse an, oder „Alle Ereignisse“, dann auch künftige. Je Projekt sind bis zu 25 Ereignis-Webhooks möglich. Den geheimen Schlüssel (whsec_…) siehst du nur direkt nach dem Anlegen.
Zur Wahl stehen Ereignisse zu Kontakten (angelegt, geändert, Tag oder Liste hinzugefügt bzw. entfernt), zum Newsletter (bestätigt, abgemeldet), zu E-Mails (geöffnet, geklickt, unzustellbar, Spam-Meldung), zu Formularen und Quiz, Bestellungen (angelegt, bezahlt, Status geändert), verlassenen Warenkörben, Bewertungen, Widerrufen, Kundenkonten, Abos, Terminen, Veranstaltungen und Anmeldungen, zur Community, zu Kursen und Zugängen. Technisch heißen sie etwa contact.created, order.paid oder appointment.created.
Jede Zustellung ist ein POST mit JSON: id (evt_…), event, createdAt, projectId und data mit dem Kontakt (Name, E-Mail, Telefon, Firma, Tags, Listen, eigene Eigenschaften) und den Daten des Ereignisses, etwa der Bestellung oder des Termins. Dazu kommen die Header X-BirdBuild-Event, X-BirdBuild-Delivery, X-BirdBuild-Timestamp und X-BirdBuild-Signature.
Als zugestellt gilt eine Antwort mit 2xx innerhalb von 10 Sekunden. Sonst versucht BirdBuild es noch zweimal, nach 30 Sekunden und nach 5 Minuten; auf 410 folgt kein weiterer Versuch. Eine Zustellung kann auch doppelt ankommen: Dein Empfänger erkennt Wiederholungen an X-BirdBuild-Delivery bzw. der id. Nach 50 Fehlschlägen in Folge pausiert der Webhook, du bekommst einmal Bescheid und schaltest ihn nach der Prüfung wieder ein. „Test senden“ schickt ein Ereignis ping, das „Zustell-Protokoll“ zeigt die Zustellungen der letzten 14 Tage. Je Konto sind 50.000 Zustellungen am Tag möglich.
Signatur prüfen
Jede Zustellung ist signiert: X-BirdBuild-Signature ist sha256= und der HMAC-SHA256 mit dem geheimen Schlüssel des Ereignis-Webhooks über den Wert von X-BirdBuild-Timestamp (Unix-Zeit in Sekunden), einen Punkt und den unveränderten Body. Rechne denselben Wert nach und vergleiche; verwirf Zustellungen mit falscher Signatur oder einem stark abweichenden Zeitstempel. Das n8n-Beispiel macht das mit den Knoten „Signatur berechnen“ und „Signatur gültig?“.
Zugangsdaten
Zugangsdaten speichern Schlüssel für fremde Schnittstellen, damit sie nie im Klartext in einem Ablauf oder Protokoll stehen. Arten: Bearer-Token, Benutzername und Passwort, Eigener Header, Query-Parameter und Telegram-Bot (Token von @BotFather). Gespeichert wird verschlüsselt, sichtbar bleiben nur Name, Art und die letzten Zeichen. Je Projekt sind bis zu 100 Zugangsdaten möglich.
Du wählst sie in der HTTP-Anfrage und bei Telegram in der Chat-Nachricht aus. Die Liste zeigt, in welchen Automatisierungen sie verwendet werden und wann sie zuletzt genutzt wurden. Über „Bearbeiten“ ersetzt du den geheimen Wert. Löschst du verwendete Zugangsdaten, scheitern die betroffenen Schritte, bis du andere wählst.
Datenschutz
HTTP-Anfragen, Chat-Nachrichten und Ereignis-Webhooks schicken Daten an Adressen, die du selbst einträgst. Dafür bist du verantwortlich: Du brauchst eine Rechtsgrundlage und ggf. einen AV-Vertrag mit dem Empfänger. In der Datenschutzerklärung deiner Website deckt das die Funktion „Automatisierungen an externe Dienste“ im Rechtstexte-Assistenten ab. Sie ist vorausgewählt, sobald eine aktive Automatisierung oder ein eingeschalteter Ereignis-Webhook Daten nach außen sendet. Läufe bewahrt BirdBuild 30 Tage auf, Zustell-Protokolle 14 Tage, jeweils gekürzt und ohne geheime Werte.
Sicherung und Konto-Übertrag
Zugangsdaten und Ereignis-Webhooks kommen weder in eine Sicherung noch zu einem anderen Konto, weil sie verschlüsselt an dein Konto gebunden sind. Lege sie danach neu an. Webhook-Auslöser bekommen eine neue Adresse und brauchen einen neuen geheimen Schlüssel; trag beides im sendenden Dienst neu ein. BirdBuild weist nach dem Einspielen darauf hin.
Häufige Fragen
Wie starte ich eine Automatisierung von einem anderen Dienst aus?
Leg eine Automatisierung mit dem Auslöser „Webhook empfangen“ an, stell die Absicherung auf „Geheimer Schlüssel im Header“ und kopier Adresse und Schlüssel. Unter „Beispielaufruf“ steht beim Reiter n8n ein fertiger Knoten „HTTP Request“, den du in n8n einfügst. Aktiviere die Automatisierung, sonst startet der Aufruf nichts.
Warum startet mein Webhook den Ablauf nicht?
Prüf zuerst, ob die Automatisierung aktiv ist. Die Antwort auf den Aufruf hilft weiter: 404 heißt, die Adresse ist unbekannt oder die Automatisierung nicht aktiv, 401, dass Schlüssel oder Signatur nicht passen, 400 ungültiges JSON und 429 zu viele Aufrufe in kurzer Zeit. Im Reiter „Läufe“ siehst du jeden gestarteten Lauf.
Wie prüfe ich, dass ein Ereignis wirklich von BirdBuild kommt?
Bilde den HMAC-SHA256 mit dem geheimen Schlüssel des Ereignis-Webhooks über den Wert von X-BirdBuild-Timestamp, einen Punkt und den unveränderten Body. Das Ergebnis muss mit X-BirdBuild-Signature nach „sha256=“ übereinstimmen. Das n8n-Beispiel unter Integrationen erledigt das ohne Code.
Was passiert, wenn mein Empfänger nicht erreichbar ist?
BirdBuild versucht jede Zustellung bis zu dreimal: sofort, nach 30 Sekunden und nach 5 Minuten. Nach 50 Fehlschlägen in Folge pausiert der Ereignis-Webhook, du bekommst einmal Bescheid und schaltest ihn nach der Prüfung wieder ein. Was zugestellt wurde, zeigt das Zustell-Protokoll der letzten 14 Tage.
Ich habe den geheimen Schlüssel nicht kopiert. Wie komme ich wieder dran?
Gar nicht, BirdBuild zeigt geheime Schlüssel nur einmal. Beim Webhook-Auslöser erzeugst du mit „Neuen Schlüssel erzeugen“ einen neuen, bei Zugangsdaten ersetzt du den geheimen Wert über „Bearbeiten“. Einen Ereignis-Webhook legst du neu an und löschst den alten.
Muss die Weitergabe an externe Dienste wie Make oder Slack in meine Datenschutzerklärung?
Ja, sobald dabei personenbezogene Daten an den Dienst gehen. Im Rechtstexte-Assistenten gibt es dafür die Funktion „Automatisierungen an externe Dienste“. BirdBuild wählt sie vor, wenn eine aktive Automatisierung oder ein Ereignis-Webhook Daten nach außen sendet. Mit dem Empfänger brauchst du ggf. einen AV-Vertrag.