Zum Hauptinhalt springen
Webhooks ermöglichen es AgencyHandy, Daten sofort an Ihre externen Systeme zu übertragen, wenn sich etwas ändert — ohne Polling. Wenn ein konfiguriertes Ereignis ausgelöst wird (beispielsweise wird eine Bestellung aktualisiert oder ein Ticket erstellt), sendet AgencyHandy eine HTTP-POST-Anfrage mit einer JSON-Nutzlast an die von Ihnen angegebene Endpunkt-URL. Dies erleichtert es, externe Tools wie CRMs, Abrechnungssysteme oder benutzerdefinierte Dashboards in Echtzeit mit Ihrem AgencyHandy-Workspace zu synchronisieren.
Workspaces mit dem Business Pro-Plan unterstützen bis zu 30.000 Webhook-Ereignisse pro Abrechnungszeitraum. Überprüfen Sie Ihre Planlimits, bevor Sie Hochvolumen-Automatisierungen einrichten.

​
Unterstützte Ereignisse

Sie können einen Webhook für jede Kombination der folgenden Ereignisse abonnieren:
KategorieEreignisse
ServiceErstellt, Aktualisiert, Gelöscht
BestellungErstellt, Aktualisiert, Gelöscht
AufgabeErstellt, Zugewiesen, Abgeschlossen, Aktualisiert
RechnungStatus geändert
Kunde / BenutzerNeuer Kunde hinzugefügt, Kunde/Benutzer gelöscht
AngebotGesendet, Empfangen, Akzeptiert, Abgelehnt
TicketErstellt, Zugewiesen, Status geändert
ZahlungEmpfangen, Fehlgeschlagen
Service-PaketErstellt, Aktualisiert, Gelöscht

​
Einen Webhook erstellen

1

Zu Webhook-Verwaltung navigieren

Navigieren Sie in der linken Seitenleiste zu Integrationen → Webhooks Management.
2

Token authentifizieren

Klicken Sie auf die Schaltfläche Management, um Ihr Webhook-Token zu authentifizieren. Dieses Token wird verwendet, um ausgehende Nutzlasten zu signieren, sodass Sie verifizieren können, dass sie von AgencyHandy stammen.
3

Neuen Webhook erstellen

Klicken Sie auf Neuen Webhook erstellen, um das Webhook-Konfigurationsformular zu öffnen.
4

Endpunkt-URL eingeben

Geben Sie im Feld Endpunkt-URL die URL des externen Systems ein, das die Webhook-Daten empfangen soll. Dies muss ein öffentlich zugänglicher POST-Endpunkt sein.
5

Inhaltstyp auswählen

Wählen Sie JSON als Inhaltstyp. AgencyHandy sendet alle Webhook-Nutzlasten als application/json.
6

Webhook-Ereignisse auswählen

Wählen Sie jedes Ereignis aus, das diesen Webhook auslösen soll. Sie können Ereignisse aus mehreren Kategorien auswählen — zum Beispiel können Bestellung: Erstellt und Rechnung: Status geändert beide auf denselben Endpunkt verweisen.
7

Webhook aktivieren

Schalten Sie den Aktiv-Radiobutton um. Wenn aktiv, liefert AgencyHandy Nutzlasten für alle ausgewählten Ereignisse in Echtzeit an Ihren Endpunkt.
8

Konfiguration speichern

Überprüfen Sie Ihre Einstellungen und klicken Sie auf Speichern. Der Webhook erscheint in der Liste und beginnt sofort mit der Ereignislieferung.

​
Einen Webhook testen

Senden Sie nach der Erstellung eines Webhooks eine Test-Nutzlast, um zu bestätigen, dass Ihr Endpunkt erreichbar ist und Daten korrekt verarbeitet.
1

Webhook öffnen

Klicken Sie in der Webhooks-Verwaltungsliste auf den Webhook, den Sie testen möchten.
2

Auf Testereignis klicken

Klicken Sie auf der Webhook-Detailseite auf die Schaltfläche Testereignis.
3

Testereignis auswählen

Wählen Sie ein Beispielereignis aus der Liste der für diesen Webhook konfigurierten Ereignisse aus (z. B. Bestellung: Erstellt).
4

Test-Nutzlast senden

Klicken Sie auf Senden. AgencyHandy sendet eine Beispiel-Nutzlast an Ihre Endpunkt-URL.
5

Ergebnis überprüfen

Überprüfen Sie Ihr externes System, um zu bestätigen, dass die Test-Nutzlast angekommen ist und wie erwartet verarbeitet wurde. Klicken Sie in AgencyHandy in den Webhook, um dessen Verlauf einzusehen — Sie können die vollständige Anfrage, die Antwort Ihres Endpunkts sehen und jedes vergangene Ereignis bei Bedarf erneut zustellen.
Verwenden Sie ein Tool wie Webhook.site oder RequestBin als temporären Endpunkt während der Einrichtung, um die genaue Nutzlaststruktur zu überprüfen, bevor Sie Ihr echtes System anschließen.

​
Webhook-Nutzlasten authentifizieren

Jede ausgehende Webhook-Anfrage von AgencyHandy enthält einen Signatur-Header, den Ihr Endpunkt verwenden kann, um zu verifizieren, dass die Nutzlast authentisch ist und nicht manipuliert wurde.

​
Signatur-Header

x-ah-sig: <signature>
AgencyHandy fügt diesen Header zu jeder Webhook-Anfrage hinzu. Extrahieren Sie den Wert aus eingehenden Anfragen und übergeben Sie ihn an den Verifizierungsendpunkt.

​
Eine Webhook-Signatur verifizieren

Senden Sie die folgende Anfrage, um zu bestätigen, dass eine Nutzlast authentisch ist: 
POST https://api.agencyhandy.com/api/v1/webhooks/verify-signature
Content-Type: application/json
​
webhookId
string
erforderlich
Die ID des Webhooks, der das Ereignis empfangen hat. Diese finden Sie auf der Webhook-Detailseite in AgencyHandy.
​
signature
string
erforderlich
Der Wert des x-ah-sig-Headers aus der eingehenden Webhook-Anfrage.
​
secret
string
erforderlich
Das Webhook-Geheimnis, das auf der Webhook-Detailseite in AgencyHandy angezeigt wird.
​
payload
object
erforderlich
Der rohe JSON-Body, der von der Webhook-Anfrage von AgencyHandy empfangen wurde.
const url = 'https://api.agencyhandy.com/api/v1/webhooks/verify-signature';

const postData = {
  webhookId: 'your_webhook_id',
  signature: 'your_signature',   // value of x-ah-sig header
  secret: 'your_webhook_secret',
  payload: {},                   // the parsed JSON body from AgencyHandy
};

const response = await fetch(url, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(postData),
});

const data = await response.json();
console.log(data); // { "verification_status": "SUCCESS" }
Antworten
​
verification_status
string
SUCCESS wenn die Signatur gültig ist. FAILED wenn die Verifizierung fehlschlägt (HTTP 403).
Success (200)
{
  "verification_status": "SUCCESS"
}
Failure (403)
{
  "type": "PermissionError",
  "status": 403,
  "verification_status": "FAILED"
}
Halten Sie Ihr Webhook-Geheimnis vertraulich. Rotieren Sie es regelmäßig und aktualisieren Sie Ihre Verifizierungslogik unmittelbar nach der Rotation. Geben Sie es niemals in clientseitigem Code oder öffentlichen Repositories preis.

​
Wichtige Hinweise

  • Ihre Endpunkt-URL muss eine öffentlich zugängliche HTTPS-POST-URL sein.
  • Wenn Ihr Endpunkt vorübergehend nicht verfügbar ist, überprüfen Sie das Verlaufspanel des Webhooks in AgencyHandy — Sie können jedes vergangene Ereignis direkt von dort aus erneut zustellen.
  • Überwachen Sie regelmäßig die Webhook-Aktivität, um fehlgeschlagene Zustellungen oder unbefugte Zugriffsversuche zu erkennen.
  • Webhooks, die wiederholt fehlschlagen, können von AgencyHandy pausiert werden — überprüfen Sie die Zustellprotokolle, um Probleme frühzeitig zu erkennen.