Cypress Cloud Webhooks sind HTTP Requests, die Cypress Cloud automatisch an einen eigenen Endpunkt schickt, sobald ein Run fertig ist. Der Body ist ein flaches JSON mit Status, Testzahlen, Branch, Commit und dem Link zum Run.
Damit hört Cypress Cloud nicht mehr bei den eingebauten Integrationen auf. Slack, Teams, GitHub und Jira gibt es dort schon fertig. Mit einem Webhook entscheidest du selbst, was danach passiert: eine eigene Slack Nachricht, ein Jira Ticket, ein Deploy, ein Eintrag im Dashboard oder ein Workflow in n8n.
Das Prinzip ist Push statt Pull. Niemand muss Cypress Cloud nach jedem Run abfragen. Der fertige Run kommt von selbst, und dein System reagiert darauf. Laut Cypress Doku richtest du Webhooks pro Projekt ein, bis zu fünf Stück.
Bei uns läuft Cypress mit Cypress Cloud täglich in Production, in GitHub Actions und GitLab CI. Workflows automatisieren wir mit n8n auf eigenen Servern in Deutschland, das Backend bauen wir mit Symfony. Genau an dieser Stelle setzen Webhooks an: ein fertiger Run kommt rein, ein Workflow entscheidet, was passiert. Roland Golla ist offizieller Cypress Ambassador und kennt die Werkzeuge von Cypress Cloud aus erster Hand.
Wir helfen Teams, Webhooks sauber an ihre Pipeline anzuschließen, mit Signatur Prüfung, Deduplizierung und klaren Regeln für rote Runs. Das Handwerk dahinter üben wir im Cypress Workshop mit Roland Golla oder in der Cypress Remote Schulung für Teams. Wer Cypress gar nicht selbst betreiben will, bekommt das NCA Cypress E2E Testing Setup. Wie ein KI Agent die Details zu einem gemeldeten Run abholt, zeigt Cypress Cloud MCP für KI Agenten. Eingebettet ist alles in eine CI CD Pipeline mit Docker und Staging.
Ein Tag inhouse mit Roland Golla, offizieller Cypress Ambassador und seit über 20 Jahren in Testing und Refactoring zu Hause. Auf unserem YouTube Kanal zeigt er in über 70 Live Coding Tutorials, wie Cypress in echten Projekten läuft. Dazu kommt unser Open Source Plugin NCA TESTIFY: Basistests für jede Website, mit einer Zeile im CI/CD Setup. Im Workshop lernt euer Team Setup, stabile Selektoren, Custom Commands und Tests in der Pipeline.
Ein Webhook feuert nicht bei jedem Klick in Cypress Cloud. Er hängt an Events, die du beim Anlegen auswählst. Mindestens eins muss aktiv sein.
Das wichtigste Event ist run.completed. Es kommt, sobald ein Run einen Endstatus hat: passed, failed, errored, timedOut oder cancelled. Dazu kommen zwei Events für die Reports, die nach dem Run verarbeitet werden. Eins für Accessibility Tests in Cypress, eins für Cypress UI Coverage.
Wichtig für die Auswertung: Bei den Report Events gibt es zwei Status. Der obere gehört zum Run, der im Report Objekt zur Verarbeitung des Reports. Ein grüner Run kann also einen Report haben, dessen Verarbeitung fehlgeschlagen ist.
Das Setup dauert ein paar Minuten. Du brauchst die Rolle Owner, Admin oder Team Admin in der Organisation und einen öffentlich erreichbaren Endpunkt, der POST Requests annimmt.
Danach schickst du mit Send test einen Beispiel Payload an deinen Endpunkt. Der läuft durch dieselbe Signatur und Zustellung wie ein echtes Event. So prüfst du Parser und Signatur, bevor der erste echte Run kommt.
Jeder Webhook zeigt in der Liste den Status der letzten Zustellung. Du kannst ihn abschalten, ohne die Konfiguration zu verlieren. Löschen entfernt dagegen auch die komplette Zustellhistorie.
Der Body ist ein flaches JSON Objekt. Für die meisten Workflows reichen wenige Felder: status, totalFailed, commitBranch und runUrl. Ein gekürztes Beispiel mit Beispielwerten:
{
"runNumber": 42,
"runUrl": "https://cloud.cypress.io/projects/abc123/runs/42",
"projectName": "Mein Projekt",
"status": "failed",
"totalTests": 120,
"totalFailed": 3,
"flakyTestCount": 1,
"commitBranch": "main",
"commitSha": "abc123",
"tags": ["nightly"],
"groups": ["chrome"]
}
Dazu kommen Commit Daten wie Message, Autor Name und Autor Mail, CI Daten wie Provider, Build ID und Pull Request sowie Dauer und Anzahl der Specs. Fehlen Commit oder CI Infos, liegt das meist an Umgebungsvariablen, die im Container nicht ankommen.
Die Metadaten stecken in den Headern:
Deine Payload URL ist öffentlich erreichbar. Jeder, der sie kennt, kann Requests schicken. Die Signatur beweist, dass ein Request wirklich von Cypress Cloud kommt und unterwegs nicht verändert wurde. Weil der Timestamp mit signiert wird, kannst du alte Requests ablehnen.
So rechnet Cypress: HMAC SHA256 mit deinem Secret über den String aus Timestamp, einem Punkt und dem rohen Body. Das Ergebnis kommt hex kodiert mit dem Präfix sha256= in den Header. Entscheidend ist der rohe Body. Wer erst JSON parst und neu serialisiert, verändert die Bytes und die Prüfung schlägt fehl.
Die Cypress Doku zeigt Beispiele für Node.js und Python. Für unseren Symfony Stack sieht ein schlanker Controller so aus:
#[Route('/webhook/cypress', methods: ['POST'])]
public function cypress(Request $request): Response
{
$signature = $request->headers->get('X-Cypress-Signature', '');
$timestamp = $request->headers->get('X-Cypress-Timestamp', '');
$rawBody = $request->getContent();
if ($signature === '' || abs(time() - (int) $timestamp) > 300) {
return new Response('Bad Request', 400);
}
$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $this->webhookSecret);
if (!hash_equals($expected, $signature)) {
return new Response('Invalid signature', 401);
}
$event = json_decode($rawBody, true, 512, JSON_THROW_ON_ERROR);
// Event-Id aus X-Cypress-Event-Id prüfen, dann in die Queue legen
return new Response('ok', 200);
}
Drei Details machen den Unterschied:
Den Controller sichern wir wie jeden anderen Code mit PHPUnit ab: ein Test mit gültiger Signatur, einer mit falscher, einer mit altem Timestamp.
Webhooks kommen mindestens einmal an, manchmal öfter. Schlägt eine Zustellung fehl, versucht Cypress Cloud es erneut, mit wachsenden Abständen und etwas Zufall dazwischen. Laut Doku sind es maximal zehn Versuche.
Wiederholt wird bei:
Nicht wiederholt wird bei 3xx Antworten, anderen 4xx Antworten und blockierten Zielen. Auch Test Sends laufen nur einmal.
Daraus folgt eine einfache Regel für deinen Endpunkt: Merk dir jede X-Cypress-Event-Id, die du schon verarbeitet hast. Kommt sie noch einmal, antworte mit 200 und tu nichts. Sonst bekommst du bei einem Retry zwei Jira Tickets oder zwei Deploys.
In Cypress Cloud siehst du unter Recent deliveries bis zu 100 Zustellungen pro Webhook, mit Request, Response und jedem einzelnen Versuch. Sensible Header wie Authorization werden dort geschwärzt. Fehlgeschlagene Zustellungen kannst du per Redeliver neu senden, mit derselben Event Id.
Du musst keinen eigenen Empfänger programmieren. Die Payload URL kann auch eine Adresse sein, die ein Tool für dich erzeugt. Cypress nennt in der Doku unter anderem Slack Workflow Builder, Microsoft Teams Workflows, Jira Automation, PagerDuty sowie Zapier, Make und n8n.
Was Teams damit typischerweise bauen:
Ein Tipp aus der Doku, den viele übersehen: Prüfe auf alles außer passed, nicht nur auf failed. Sonst rutschen errored und timedOut ohne Meldung durch.
Der Haken bei No Code Zielen: Viele können keine HMAC Signatur über den rohen Body rechnen. Dann ist die URL selbst das Geheimnis. Sie gehört nicht ins Repository und nicht in einen Chat. Wir setzen hier auf n8n auf eigenen Servern. Dort bleibt die Kette im eigenen Netzwerk, und mit etwas Code lässt sich die Signatur trotzdem prüfen. Wie wir n8n per MCP an Agenten anbinden, steht bei Web MCP.
Ein Webhook sagt dir, dass etwas passiert ist. Er sagt dir nicht, warum ein Test rot ist. Fehlermeldungen, Stack Traces und Replays stehen nicht im Payload. Dafür gibt es die Cypress Cloud CLI und Cypress Cloud MCP.
Cypress beschreibt im eigenen Blog genau diese Arbeitsteilung. Der Webhook filtert, welche Runs Aufmerksamkeit brauchen. Erst dann holt ein Skript oder KI Agent die Details. Das spart Tokens und Requests gegenüber einem Agenten, der nach jedem Run alles abfragt.
So sieht der Ablauf in der Praxis aus:
Welche Regeln dabei für Agenten gelten, steht auf der Seite Cypress mit KI Agenten und in den NCA Agentic AI Coding Guardrails.
Ein häufiger Stolperstein bei parallelen Runs. Cypress Cloud weiß nicht sicher, ob noch eine Gruppe dazukommt. Deshalb wartet es nach der letzten bekannten Gruppe eine Weile, laut Doku standardmäßig 60 Sekunden. Erst dann ist der Run fertig, und erst dann kommt run.completed.
Die Lösung ist die Run Completion API. Du meldest am Ende deiner Pipeline, dass alle erwarteten Gruppen durch sind. Cypress Cloud überspringt die Wartezeit, und der Webhook kommt, sobald die laufenden Gruppen fertig sind.
Wie Gruppen, Maschinen und Spec Verteilung zusammenspielen, erklärt die Seite Cypress Parallelisierung. Für Webhooks, die Deploys auslösen, lohnt sich der Aufwand fast immer.
Was Cypress Cloud selbst absichert: Private, Loopback und Link Local Adressen sind als Ziel gesperrt, das schützt vor Server Side Request Forgery. Jeder Versuch bricht nach zehn Sekunden ab. Secrets liegen verschlüsselt und werden nie wieder angezeigt. Wichtig: Das Secret signiert, es verschlüsselt nicht. Für vertrauliche Daten brauchst du HTTPS.
Ein Punkt für den Datenschutz: Der Payload enthält Name und Mail des Commit Autors. Das sind personenbezogene Daten. Schickst du den Webhook an einen US Dienst als Zwischenstation, wandern diese Daten mit. Filtere die Felder deshalb früh heraus, wenn du sie nicht brauchst, oder empfange den Webhook auf eigener Infrastruktur in Deutschland.
Für die Tests selbst gilt die gleiche Regel wie immer: nur Fake Daten in Testläufen. Warum, erklärt die Seite Testdaten in Cypress.
Using webhooks is a great solution for custom integrations.
Cypress Cloud MCP verbindet KI Agenten direkt mit Testergebnissen, Flaky Tests und Test Replay. Setup für OpenCode und Claude Code, eingeordnet von NCA.
Mehr erfahren
Cypress Test Replay zeigt DOM, Netzwerk und Konsole fehlgeschlagener CI Tests. So analysierst du rote Runs ohne lokales Nachstellen, eingeordnet von NCA.
Mehr erfahrenEin Webhook allein löst kein Problem. Er schickt nur eine Nachricht. Entscheidend ist, was danach passiert. Wer bekommt den roten Run? Wann wird aus einem Fehler ein Ticket? Wann ist ein Test nur flaky und wann ein echter Bug? Diese Regeln klären wir mit Teams, bevor der erste Webhook live geht.
Webhooks gehören bei uns zu den Quality Gates für KI Code. Ein grüner Run darf einen Deploy auslösen, ein roter stoppt ihn. Mit den Report Events landen auch Accessibility Testing Ergebnisse dort, wo das Team ohnehin hinschaut.
Aufbauen kannst du das mit unserer Vibe Coding Beratung. Passend dazu im NCA Cypress Glossar: Cypress UI Coverage für die Lücken in deinen Tests und Cypress Parallelisierung für schnellere Runs.
Optimieren Sie Ihre Webseite mit Astro JS und nutzen Sie die Vorteile einer schnellen, sicheren und barrierefreien Webseite. Erfüllen Sie die gesetzlichen Anforderungen und verbessern Sie die Benutzererfahrung Ihrer Webseite. Mit Astro JS können Sie die Ladezeit reduzieren, die Sicherheit maximieren und die SEO-Optimierung verbessern. Kontaktieren Sie uns, um mehr zu erfahren und um Ihre Webseite auf ein neues Level zu heben.
Die wichtigsten Fragen zu Events, Einrichtung, Signatur, Retries und Datenschutz bei Cypress Cloud Webhooks.
Cypress Cloud Webhooks sind HTTP Requests, die Cypress Cloud an einen eigenen Endpunkt schickt, sobald ein ausgewähltes Event eintritt, etwa ein fertiger Run. Der Body ist ein flaches JSON mit Status, Testzahlen, Branch, Commit und dem Link zum Run. Damit baust du eigene Automationen, die über die eingebauten Integrationen für Slack, Teams, GitHub und Jira hinausgehen.
Laut Cypress Doku gibt es drei Events. run.completed feuert, wenn ein Run einen Endstatus hat. run.accessibility.completed kommt, sobald der Accessibility Report fertig verarbeitet ist. run.uiCoverage.completed folgt, wenn der UI Coverage Report fertig ist. Beim Anlegen wählst du mindestens ein Event aus. Cypress kündigt an, den Bereich anhand von Feedback weiter auszubauen.
Laut Cypress stehen Webhooks in allen bezahlten Cypress Cloud Plänen zur Verfügung. Im kostenlosen Plan sind sie nicht enthalten. Zum Anlegen und Bearbeiten brauchst du außerdem die Rolle Owner, Admin oder Team Admin in der Organisation. Ansehen können Webhooks alle, die Zugriff auf das Projekt haben. Pro Projekt sind bis zu fünf Webhooks möglich.
Setze beim Anlegen ein Secret. Cypress schickt dann den Header X-Cypress-Signature mit einer HMAC SHA256 Signatur über Timestamp, Punkt und rohen Body. Dein Endpunkt rechnet dieselbe Signatur mit dem Secret nach und vergleicht in konstanter Zeit, in PHP mit hash_equals. Wichtig ist der rohe Body. Geparstes und neu serialisiertes JSON führt zu falschen Ergebnissen.
Cypress Cloud versucht es erneut, laut Doku bis zu zehn Versuche mit wachsenden Abständen. Wiederholt wird bei Netzwerkfehlern, HTTP 408, 429 und allen 5xx Antworten. Andere 4xx und 3xx Antworten gelten als endgültiger Fehler. Fehlgeschlagene Zustellungen siehst du unter Recent deliveries und kannst sie dort per Redeliver mit derselben Event Id neu senden.
Webhooks werden mindestens einmal zugestellt. Bei einem Retry oder einem manuellen Redeliver kann dasselbe Event mehrfach ankommen. Deshalb gibt es den Header X-Cypress-Event-Id, der über alle Versuche gleich bleibt. Speichere verarbeitete Ids und antworte bei einer Wiederholung einfach mit 200, ohne erneut zu handeln. So entstehen keine doppelten Tickets oder Deploys.
Nein. Die Payload URL kann auch von einem Tool stammen, etwa Slack Workflow Builder, Jira Automation, PagerDuty oder n8n. Viele No Code Tools können die HMAC Signatur allerdings nicht prüfen. Dann ist die URL selbst das Geheimnis und gehört weder ins Repository noch in einen Chat. Mit n8n auf eigenen Servern bleibt die Kette im eigenen Netzwerk.
Bei parallelen oder gruppierten Runs wartet Cypress Cloud nach der letzten bekannten Gruppe eine Weile, laut Doku standardmäßig 60 Sekunden. Es könnte ja noch eine Gruppe dazukommen. Erst danach ist der Run fertig und der Webhook wird gesendet. Mit der Run Completion API meldest du das Ende selbst, und die Wartezeit entfällt.
Die eingebaute Slack Integration postet Run Ergebnisse in einem festen Format. Mit einem Webhook bestimmst du Text, Felder, Channel und Bedingungen selbst. Du kannst etwa nur rote Runs auf main melden oder den Commit Autor direkt anschreiben. Für einfache Benachrichtigungen reicht die eingebaute Integration. Für eigene Regeln ist der Webhook der flexiblere Weg.
Nein. Der run.completed Payload enthält Zahlen, Status, Commit und CI Daten, aber keine Fehlermeldungen, Stack Traces oder Screenshots. Für die Details nutzt du Cypress Cloud CLI oder Cypress Cloud MCP. Cypress empfiehlt genau diese Kombination: Der Webhook filtert die wichtigen Runs, danach holt ein Skript oder KI Agent gezielt die Fehler und Test Replay Daten.
Mit Bedacht ja. Der Payload enthält Name und Mail des Commit Autors, also personenbezogene Daten. Läuft der Webhook über einen US Dienst als Zwischenstation, wandern diese Daten mit. Empfange den Webhook deshalb am besten auf eigener Infrastruktur in Deutschland und filtere unnötige Felder früh heraus. In den Tests selbst gehören nur Fake Daten.
Ja. Du richtest die Payload URL auf einen Build Hook deines Deploy Systems oder auf einen Workflow, der den Deploy startet. Prüfe im Workflow, ob status gleich passed ist und der Branch stimmt. Bei parallelen Runs lohnt sich die Run Completion API, damit der Deploy nicht unnötig wartet. So wird ein grüner Run zum echten Quality Gate.
