Smart API

Die Smart API bietet alle Endpunkte, die zur Erstellung einer Integration erforderlich sind. Sie ist für Server-zu-Server-Integrationen und nicht für Native Apps oder Webanwendungen für Endbenutzer konzipiert. Daher bietet sie nur API Keys für die Authentifizierung. Gehen Sie zur Smart API-Dokumentation oder laden Sie die OpenAPI-Spezifikation der Smart API herunter, um loszulegen.

Webhooks sind die bevorzugte Methode zur Erstellung von Integrationen, die ereignisgesteuerte Informationen von der Smart API erwarten. Die andere Möglichkeit wäre, einen Smart-API-Endpunkt in einem bestimmten Intervall abzufragen, was eine größere Belastung für die Smart-API und das System bedeuten würde, das die Anfragen sendet.
Die Smart API stellt Webhooks über Automatisierungen zur Verfügung und ermöglicht es, Webhooks nur für ausgewählte Ereignisse oder für alle Ereignisse einzurichten.

Wie funktionieren Webhooks?

Webhooks vs. Websockets

Webhooks sollten nicht mit Websockets verwechselt werden. Webhooks sind Benachrichtigungen, die von einem Server an einen anderen gesendet werden, während Websockets die Echtzeitkommunikation zwischen Servern und Clients ermöglichen.

Schurter Smart API signiert Webhook-Anfragen durch Generierung eines hashbasierten Nachrichtenauthentifizierungscodes (HMAC) mit SHA-256.

Um die von Ihrer Plattform empfangenen Anfragen zu validieren, führen Sie die folgenden Schritte aus:

Extrahieren Sie den Zeitstempel und die Signatur aus dem Header namens X-Signature (z. B. v=1;t=1701252447;sig=0102030405060708).

Erstellen Sie dieselbe Zeichenkette, die zur Erzeugung der Signatur verwendet wurde, indem Sie den Zeitstempel, das Zeichen . und den empfangenen UTF-8-kodierten Anfragebody (z. B. 1701252447.SampleRequestBody) aneinanderhängen.

Generieren Sie einen HMAC mit SHA256 der verketteten UTF-8 kodierten Zeichenfolge. Verwenden Sie das Webhook-Signaturgeheimnis als Schlüssel.

Vergleichen Sie die empfangene Signatur mit der generierten Signatur. Wenn die Signaturen übereinstimmen, prüfen Sie, ob der empfangene Zeitstempel innerhalb Ihrer Toleranz liegt (z.B. 5 Minuten).