Dokumentation der API

Benachrichtigungen über Teams und Webhook

Stonewake kann eine Meldung über Ihren Bestand in dem Moment, in dem sie entsteht, in Ihre eigenen Systeme senden, entweder in einen Microsoft Teams Kanal über die Workflows App oder an einen eigenen Webhook, der bei jeder Nachricht eine Signatur prüft. Eine Administratorin oder ein Administrator des Arbeitsbereichs richtet beides auf der Einstellungsseite des Dashboards ein. Alles Folgende ist auch über die API und für Assistenten mit KI über MCP lesbar, die einen Kanal nur lesen und nie ändern.

Was eine Meldung ist

Eine Meldung entsteht, wenn sich der Zustand Ihres Bestands ändert, etwa wenn ein Engagement auf Rot wechselt, ein beobachtetes Unternehmen ein Registerereignis erhält oder die Nachrichten über ein ernstes Ereignis zu einem Unternehmen aus Ihrem Bestand oder Ihrer Beobachtungsliste berichten (Nachrichtenbeobachtung), und zwar im selben Schritt, der die Änderung festhält. Eine Meldung kündigt daher nie eine Änderung an, die zurückgenommen wurde. Eine Meldung nennt ihre Ereignisklasse, ihren Schweregrad (kritisch, hoch oder Information), die Daten und die Kennungen ihres Gegenstands und nie einen Namen. Ein Kanal für ein Team erhält die Meldungen dieses Teams und jene für den ganzen Arbeitsbereich, ein Kanal für den ganzen Arbeitsbereich erhält alle, beide nur für die Bereiche von Stonewake, die das Team hält. Eine Tatsache, die bei der Erstellung ihrer Meldung schon alt war, wird für die tägliche Zusammenfassung vermerkt und nicht gesendet.

Microsoft Teams

Microsoft hat die Office 365 Connectors in Teams im Mai 2026 eingestellt und nennt die Workflows App als Ersatz. Stonewake sendet daher über einen Workflow an Teams.

  • Öffnen Sie in Teams den Kanal, wählen Sie Workflows und die Vorlage Send webhook alerts to a channel (oder bauen Sie einen Flow auf dem Auslöser When a Teams webhook request is received).
  • Speichern Sie den Workflow und kopieren Sie seinen Webhook Link.
  • Öffnen Sie in Stonewake die Einstellungen, fügen Sie einen Kanal der Art Microsoft Teams hinzu und fügen Sie den Link ein.

Angenommen wird nur eine Adresse unter einem Workflows Host, den Microsoft dokumentiert (environment.api.powerplatform.com, und logic.azure.com für ältere Flows). Der Link trägt seine eigene Signatur, daher bewahrt Stonewake ihn versiegelt wie ein Passwort auf und zeigt ihn nie wieder an. Jede Meldung kommt als Adaptive Card in der Sprache der Meldungen Ihres Arbeitsbereichs mit einer Schaltfläche, die das Dashboard öffnet. Teams antwortet, dass es den Lauf angenommen hat, und das Posten in den Kanal ist ein eigener Schritt des Workflows. Im Zustellprotokoll steht für Teams daher Gesendet, nie Zugestellt.

Signierter Webhook

Eine Meldung per Webhook ist ein HTTPS POST mit einem JSON Inhalt und den drei Kopfzeilen des Verfahrens Standard Webhooks.

  • webhook-id benennt die Zustellung. Sie bleibt bei jeder Wiederholung derselben Zustellung gleich, damit Ihr Empfänger eine Wiederholung verwerfen kann.
  • webhook-timestamp ist der Zeitpunkt dieses Versuchs in Sekunden seit dem 1. Januar 1970 (UTC).
  • webhook-signature ist v1, gefolgt vom Base64 eines HMAC SHA256 über webhook-id, einen Punkt, webhook-timestamp, einen Punkt und den unveränderten Inhalt, mit Ihrem Signaturschlüssel als Schlüssel.

Der Signaturschlüssel beginnt mit whsec_ und wird einmal angezeigt, wenn der Kanal angelegt wird. Bewahren Sie ihn in Ihrem eigenen Schlüsselspeicher auf. Zum Prüfen einer Nachricht berechnen Sie die Signatur über den Inhalt, wie er ankam, vergleichen sie in konstanter Zeit und weisen einen Zeitstempel zurück, der mehr als fünf Minuten von Ihrer Uhr abweicht. Das verhindert eine Wiederholung durch Dritte. Die offiziellen Bibliotheken von Standard Webhooks erledigen alle drei Schritte.

Der Inhalt trägt type (stonewake.alert), version, content_class, event_id, severity, einen Satz in text und einen link ins Dashboard. Der Satz steht in der Sprache der Meldungen Ihres Arbeitsbereichs, Deutsch, sofern die Administration auf der Einstellungsseite nicht Englisch gewählt hat; die Schlüssel und version sind in beiden Sprachen dieselben. Ein Kanal mit der Einstellung ausführlich trägt außerdem event_class, occurred_at, created_at, node_id, exposure_id und source, die Art und die Kennung des Datensatzes, auf dem die Meldung beruht und den das Dashboard in seine Quellenangaben auflöst. Ein Nachrichtenereignis (press_candidate) trägt außerdem news mit seinem event_type und der Zahl seiner articles, languages und sources, und eine ausführliche Teams Karte zeigt dasselbe in einer Zeile Nachrichten. Ein Kanal mit der Einstellung minimal trägt keinen Gegenstand. Eine Antwort 2xx ist die Bestätigung Ihres Empfängers und steht im Protokoll als Zugestellt.

Wiederholungen und Aufgabe

Eine Zustellung, die aus einem vorübergehenden Grund scheitert, etwa an einer Antwort 5xx, 408, 425 oder 429, an einer Zeitüberschreitung oder an einem Verbindungsfehler, wird nach 30 Sekunden, 2 Minuten, 8 Minuten, 32 Minuten und danach stündlich wiederholt, acht Versuche insgesamt, in weniger als vier Stunden. Jeder Versuch wird festgehalten. Eine Zustellung, deren Fehler durch Warten nicht vergeht, wird sofort aufgegeben und steht als Aufgegeben im Protokoll. Das gilt für eine andere Antwort 4xx, für eine Adresse, die die Prüfungen unten nicht besteht, und für einen Kanal, der deaktiviert wurde, während die Meldung unterwegs war. Eine Zustellung, deren Versuche aufgebraucht sind, steht ebenfalls als Aufgegeben im Protokoll. Nichts entfällt ohne eine Zeile im Protokoll.

Prüfung der Adressen

Jede Adresse wird beim Anlegen des Kanals und erneut vor jedem Versand geprüft.

  • Nur HTTPS, auf dem Standardport, ohne Benutzernamen und Passwort in der Adresse.
  • Ein Hostname, nie eine IP Adresse, in einfachen ASCII Zeichen.
  • Jede Adresse, in die der Name aufgelöst wird, muss öffentlich sein. Private, Loopback und Link Local Adressen sowie die Metadatenadressen der Cloud werden abgewiesen, und die Verbindung wird nur zu einer Adresse geöffnet, die in diesem Moment geprüft wurde. Ein Name, der seine Antwort zwischen Prüfung und Aufruf ändert, erreicht daher nie eine interne Adresse.
  • Weiterleitungen werden nie verfolgt.
  • Ihr Arbeitsbereich kann eine Freigabeliste von Hosts haben. Bitten Sie Ihren Ansprechpartner bei Stonewake, sie einzurichten. Ist sie eingerichtet, wird eine Adresse außerhalb der Liste abgewiesen.

Testnachrichten und der Testempfänger

Testnachricht senden sendet ein festes Testdokument, das kein Ereignis nennt, durch dieselben Prüfungen und zeigt die Antwort sofort an. Ein Kanal kann auch auf den Testempfänger von Stonewake zeigen, der Signatur und Zeitstempel jeder Nachricht prüft und das Ergebnis festhält. So sehen Sie eine signierte Zustellung von Anfang bis Ende, bevor Ihr eigener Empfänger bereit ist. Der Testempfänger läuft innerhalb von Stonewake. Seine Zustellungen verlassen die Plattform nie, und er hat keine öffentliche Adresse. Der Demo Arbeitsbereich stellt nur an den Testempfänger zu.

Wo jeder Teil bereitsteht

  • Dashboard. Die Einstellungsseite listet die Kanäle, legt sie an und deaktiviert sie, sendet Testnachrichten, zeigt die letzten Zustellungen und legt Sprache und Uhrzeit der Meldungen fest (Deutsch oder Englisch, deutsche oder britische Zeit). Nur für Administratoren.
  • API. GET /v1/alerts/events listet die Meldungen, und GET /v1/alerts/deliveries liefert ihren Zustellstatus, filterbar nach event_id, status und channel. Ein Schlüssel liest die Zeilen seines eigenen Teams und jene für den ganzen Arbeitsbereich.
  • MCP. alert_events und alert_deliveries lesen dasselbe, mit demselben Teamumfang.

Ein Kanal wird nur im Dashboard angelegt, getestet und deaktiviert, und nach dem Anlegen wird nie eine Adresse oder ein Schlüssel ausgeliefert.