Owlat Docs

API-Keys & Webhooks

API-Keys für den programmatischen Zugriff erstellen und ausgehende Webhooks einrichten, um Echtzeit-Benachrichtigungen zu E-Mail- und Kontaktereignissen zu erhalten.

Owlat bietet API-Keys für den programmatischen Zugriff und ausgehende Webhooks für Echtzeit-Ereignisbenachrichtigungen. Zusammen ermöglichen sie es Ihnen, Owlat in Ihren Anwendungs-Stack zu integrieren — Kontakte synchronisieren, transaktionale E-Mails auslösen und auf E-Mail-Ereignisse wie Bounces und Klicks reagieren.

API-Keys

Einen API-Key erstellen

  1. Öffnen Sie Einstellungen > Technik > API-Keys.
  2. Klicken Sie auf API-Key erstellen.
  3. Geben Sie dem Key einen sprechenden Namen (z. B. „Production Backend“ oder „Staging Sync“).
  4. Wählen Sie die Scopes (Berechtigungen) aus, die der Key haben soll — mindestens ein Scope ist erforderlich; Keys folgen dem Prinzip der minimalen Rechte.
  5. Kopieren Sie den Key sofort — er wird kein zweites Mal angezeigt.

Bewahren Sie Ihren API-Key sicher auf. Committen Sie ihn niemals in die Versionskontrolle, binden Sie ihn nicht in clientseitigen Code ein und geben Sie ihn nicht im Klartext weiter. Verwenden Sie Umgebungsvariablen oder einen Secrets-Manager.

Ihren API-Key verwenden

Übergeben Sie den API-Key in Anfragen an die Owlat-API. Details zur Authentifizierung, verfügbaren Endpunkten und SDK-Optionen finden Sie in der API-Dokumentation.

Häufige API-Anwendungsfälle:

  • Kontakte aus Ihrer Anwendung heraus anlegen und aktualisieren
  • Transaktionale E-Mails versenden (Passwort-Resets, Benachrichtigungen)
  • Eigene Ereignisse als Auslöser für Automationen erfassen
  • Kontakte programmatisch für Themen an- und abmelden

Keys verwalten

Die Key-Liste zeigt, wann jeder Key zuletzt verwendet wurde (bzw. Nie verwendet bis zum ersten Aufruf), sodass Sie Zugangsdaten erkennen, die gefahrlos ausgemustert werden können. Für jeden Key können Sie:

  • Umbenennen — den Namen des Keys direkt ändern, ohne den Key selbst zu beeinflussen.
  • Widerrufen — einen kompromittierten oder nicht mehr benötigten Key soft-deaktivieren. Er funktioniert sofort nicht mehr, bleibt aber mit dem Badge Widerrufen in der Liste sichtbar.
  • Löschen — die Zeile des Keys dauerhaft entfernen, auch bei bereits widerrufenen Keys. Das lässt sich nicht rückgängig machen.

Rotieren Sie Ihre API-Keys nach einem festen Zeitplan — auch wenn sie nicht kompromittiert wurden. Das begrenzt den Schaden, falls ein Key doch einmal nach außen gelangt.

Webhooks

Webhooks sind ausgehende HTTP-Aufrufe, die Owlat an Ihren Server sendet, wenn Ereignisse eintreten — etwa wenn eine E-Mail zugestellt, ein Link geklickt wird oder sich ein Kontakt von einem Thema abmeldet.

Einen Webhook einrichten

  1. Öffnen Sie Einstellungen > Technik > Webhooks.
  2. Klicken Sie auf Webhook erstellen.
  3. Geben Sie einen Namen und Ihre Endpunkt-URL ein — die URL auf Ihrem Server, die die Webhook-Payloads entgegennimmt.
  4. Wählen Sie die Ereignisse aus, die Sie abonnieren möchten.
  5. Speichern Sie den Webhook. Das Signing Secret wird nur einmal bei der Erstellung angezeigt — kopieren Sie es sofort.

Verfügbare Ereignisse

Owlat kann Sie über diese Ereignisse benachrichtigen:

EreignisWird ausgelöst, wenn
email.sentEine E-Mail gesendet wird
email.deliveredEine E-Mail zugestellt wird
email.bouncedEine E-Mail unzustellbar ist (Bounce)
email.openedEine E-Mail geöffnet wird
email.clickedEin Link in einer E-Mail geklickt wird
email.complainedEine Spam-Beschwerde eingeht
contact.createdEin neuer Kontakt angelegt wird
topic.unsubscribedEin Kontakt sich von einem Thema abmeldet

Abonnieren Sie nur die Ereignisse, die Sie tatsächlich benötigen. Die Verarbeitung unnötiger Webhooks verschwendet auf beiden Seiten Ressourcen.

Einen Webhook verwalten

Klappen Sie einen beliebigen Webhook unter Einstellungen > Technik > Webhooks auf, um:

  • Test senden — ein Beispielereignis test an Ihren Endpunkt zu schicken, um dessen Erreichbarkeit zu prüfen (der Webhook muss aktiviert sein).
  • Aktivieren / Deaktivieren — Zustellungen pausieren, ohne den Webhook zu löschen.
  • Secret neu erzeugen — ein neues Signing Secret ausstellen (das alte wird ungültig).
  • Zustellprotokolle — jüngste Zustellungen und Antworten einsehen (siehe unten).

Zustellprotokolle

Jeder Webhook-Endpunkt zeigt ein Zustellprotokoll, mit dem Sie Folgendes überwachen:

  • Jüngste an Ihren Endpunkt gesendete Payloads
  • HTTP-Statuscodes der Antworten
  • Fehlgeschlagene Zustellungen und Wiederholungsversuche

Ist Ihr Endpunkt nicht erreichbar oder liefert Fehler, werden Webhooks automatisch erneut versucht. Prüfen Sie das Zustellprotokoll, um Probleme zu diagnostizieren.

Signaturprüfung

Jede Zustellung wird mit HMAC-SHA256 und dem Signing Secret des Webhooks signiert. Owlat übermittelt den Hex-Digest im Header X-Signature, zusammen mit X-Timestamp (Unix-Sekunden) und X-Webhook-Id. Berechnen Sie den HMAC über den rohen JSON-Body mit Ihrem Secret neu und vergleichen Sie ihn mit X-Signature, um zu bestätigen, dass das Payload von Owlat stammt und nicht manipuliert wurde. Codebeispiele zur Verifizierung finden Sie in der API-Dokumentation.

Verifizieren Sie Webhook-Signaturen in der Produktion immer. Ohne Verifizierung könnte jeder, der Ihre Endpunkt-URL entdeckt, gefälschte Payloads senden.

Best Practices

  • Sprechende Key-Namen verwenden — „Production App v2“ sagt Ihnen mehr als „Key 1“, wenn Sie ein halbes Jahr später Ihre Keys durchsehen.
  • Keys nach Umgebung trennen — verwenden Sie unterschiedliche API-Keys für Entwicklung, Staging und Produktion.
  • Webhook-Zustellung überwachen — sehen Sie regelmäßig in die Zustellprotokolle, um Endpunktprobleme zu erkennen, bevor sie Ihre Integration beeinträchtigen.
  • Ungenutzte Zugangsdaten widerrufen — entfernen Sie alte API-Keys und inaktive Webhook-Endpunkte regelmäßig.

Nächste Schritte

WeiterFeature-Flags