Webhooks bieten dir die Möglichkeit, Echtzeit-Updates für bestimmte Ereignisse in deinem Shirtigo Cockpit zu erhalten. In diesem Artikel werden die verfügbaren Webhook-Aktionen und die Einrichtung eines Webhooks über den Create-Endpunkt erläutert. Zudem wird erklärt, wie du mithilfe des signature_header-Feldes im HTTP Header der Anfrage validieren kannst, dass die Anfrage tatsächlich durch das Shirtigo Cockpit versendet wurde. Weitergehende technische Informationen findest du auch in unserer API Dokumentation.
Um einen Webhook zu nutzen, musst du zunächst eine URL in deinem System auswählen, an die wir die Webhook-Anfragen senden können. Diese URL sollte in der Lage sein, POST-Anfragen zu empfangen und die Webhook-Daten entsprechend zu verarbeiten. Stelle sicher, dass deine URL öffentlich zugänglich ist und keine Authentifizierung erfordert, da dies die Zustellung des Webhooks beeinträchtigen kann.
Webhook-Ereignisse werden über ihren Typ definiert, der über einen Key bzw. seine Resource und Action definiert sind:
Die folgende Tabelle bietet eine Übersicht über die möglichen Webhook-Ereignisse mit Key, Ressource, Aktion und einer Beschreibung:
| Key | Ressource | Aktion | Beschreibung |
|---|---|---|---|
| Order.created | Order | created | Wird ausgelöst, wenn eine Bestellung erstellt wird |
| Order.created-failed | Order | creation-failed | Wird ausgelöst, wenn eine Bestellung nicht angelegt werden konnte. Dieser Fall tritt nur auf, wenn die als design_url übergebene Druckdatei transparente Ränder enthält und nach die Datei nach dem Cropping die Maximalmaße der Processingarea überschreitet. |
| Order.updated | Order | updated | Wird ausgelöst, wenn eine Bestellung aktualisiert wird |
| Order.shipped | Order | shipped | Wird ausgelöst, wenn eine Bestellung versandt wird |
| Order.clarification | Order | clarification | Wird ausgelöst, wenn eine Aktion notwendig ist |
| Order.canceled | Order | canceled | Wird ausgelöst, wenn eine Bestellung storniert wird |
| OrderProductItem.status_changed | Order Product Item | status_changed | Wird ausgelöst, wenn ein einzelnes Werkstück (Item) für eine Bestellposition (Order Product) seinen Status ändert |
| Product.created | Product | created | Wird ausgelöst, wenn ein Produkt erstellt wird |
| Product.updated | Product | updated | Wird ausgelöst, wenn ein Produkt aktualisiert wird |
| Product.deleted | Product | deleted | Wird ausgelöst, wenn ein Produkt gelöscht wird |
| Design.created | Design | created | Wird ausgelöst, wenn ein Design erstellt wird |
| Design.rendering_failed | Design | rendering_failed | Wird ausgelöst, wenn das Rendern eines Designs fehlschlägt |
| Design.updated | Design | updated | Wird ausgelöst, wenn ein Design aktualisiert wird |
| Design.deleted | Design | deleted | Wird ausgelöst, wenn ein Design gelöscht wird |
| GeneratedMedia.rendered | GeneratedMedia | rendered | Wird ausgelöst, ein ein MockupFactory Task abgeschlossen wurde. |
Um eine URL für einen Webhook zu registrieren, musst du eine POST-Anfrage an den /webhooks-Endpunkt senden. In dieser Anfrage gibst du die benötigten Informationen an, wie z.B. Resource, Action und die URL, an die der Webhook gesendet werden soll.
Bei der Erstellung eines Webhooks gibt es verschiedene Parameter, die in der POST-Anfrage angegeben werden können. Hier sind die möglichen Parameter und ihre Bedeutungen:
resource: Die Ressource, für die der Webhook registriert werden soll (z.B. Bestellung, Produkt, Design).action: Die Aktion, für die der Webhook registriert werden soll (z.B. erstellt, aktualisiert, gelöscht).types: Eine alternative Möglichkeit zur Angabe von Ressource und Aktion ist die Verwendung eines Array von Webhook-Typ-Schlüsseln. Dabei werden die gewünschten Webhook-Typen in Form einer Liste angegeben (z.B. ["Order.created", "Product.updated"]).url: Die URL, an die der Webhook gesendet wird. Dies ist die Adresse, an der dein System den Webhook empfängt und verarbeitet.secret: Ein optionaler geheimer Schlüssel, der verwendet wird, um den Payload mit dem SHA256-Algorithmus zu hashen und die Signatur in Webhook-Aufrufen zu erstellen. Dieser geheime Schlüssel hilft dir, die Integrität der Webhook-Daten zu überprüfen und sicherzustellen, dass sie tatsächlich von Shirtigo Cockpit stammen.signature_header: Ein optionaler Header-Parametername, der verwendet wird, um die Webhook-Signatur im Request zu identifizieren. Wenn nicht angegeben, wird standardmäßig der Header “Signature” verwendet.is_active: Ein boolescher Wert, der angibt, ob der Webhook aktiv ist. Wenn true, ist der Webhook aktiv und wird bei entsprechenden Ereignissen ausgelöst. Wenn false, wird der Webhook nicht ausgelöst.Bei der Erstellung eines Webhooks müssen entweder resource und action oder types angegeben werden, um das gewünschte Ereignis zu definieren. Die url ist ebenfalls erforderlich, da sie angibt, wohin der Webhook gesendet werden soll. Die anderen Parameter sind optional, können aber hilfreich sein, um die Sicherheit und Funktionalität deiner Webhooks zu verbessern.
Im Folgenden findest du ein Beispiel, wie du einen Webhook für die Aktion “Bestellung erstellt” erstellen kannst:
Beispiel: Erstellen eines Webhooks für die Aktion “Bestellung erstellt”:
Senden Sie eine POST-Anfrage an den Endpunkt /webhooks mit den folgenden Daten:
In diesem Beispiel registrierst du einen Webhook für das Ereignis “Bestellung erstellt” (Order.created). Der Webhook wird an die angegebene URL “https://deinserver.com/api/webhook-listener” gesendet, sobald eine neue Bestellung erstellt wird. Stelle sicher, dass die angegebene URL in deinem System existiert und korrekt konfiguriert ist, um die Webhook-Anfragen zu empfangen und zu verarbeiten.
Es ist wichtig, dass du deine eigene URL angibst, anstatt die im Beispiel verwendete URL. Die URL sollte auf deinem Server oder einer von dir verwalteten Plattform gehostet werden, damit du die Webhook-Daten empfangen und verarbeiten kannst.
Wir betrachten Webhooks als erfolgreich zugestellt, wenn wir einen HTTP-Statuscode im Bereich 2xx (z.B. 200 OK oder 204 No Content) von deinem System erhalten. Wenn die Zustellung des Webhooks fehlschlägt, weil wir einen anderen HTTP-Statuscode erhalten oder keine Antwort innerhalb eines angemessenen Zeitrahmens erhalten, versuchen wir, den Webhook erneut zu senden.
Die Wiederholungsversuche für die Zustellung von Webhooks erfolgen in ansteigenden Intervallen. Nach jedem fehlgeschlagenen Zustellversuch wird das Intervall bis zum nächsten Versuch verlängert. Wenn ein Webhook nach fünf fehlgeschlagenen Zustellversuchen immer noch nicht erfolgreich zugestellt werden konnte, wird der konfigurierte Webhook für zukünftige Ereignisse deaktiviert. Du musst den Webhook manuell reaktivieren, um weitere Updates zu erhalten.
Um sicherzustellen, dass du alle Ereignisse erfassen kannst, ist es wichtig, dass dein System in der Lage ist, auf die Webhook-Anfragen zu reagieren und einen erfolgreichen HTTP-Statuscode zurückzugeben. Achte darauf, dass deine URL verfügbar ist und dass deine Anwendung in der Lage ist, die Webhook-Daten korrekt zu verarbeiten.
Um die Integrität der empfangenen Webhook-Daten sicherzustellen, kannst du die Signatur im Request-Header mit der im Webhook erstellten Signatur vergleichen. Verwende den geheimen Schlüssel und den SHA256-Algorithmus, um den Payload zu hashen und die resultierende Signatur mit der Signatur im Request-Header zu vergleichen.
Der Feldname im Header kann über das signature_header-Feld konfiguriert werden. Standardmäßig heißt das Feld “Signature”. Du kannst einen benutzerdefinierten Feldnamen angeben, indem du das signature_header-Feld im Create-Endpunkt des Webhooks festlegst.
Um sicherzustellen, dass dein Webhook korrekt funktioniert und die erwarteten Daten empfängt, kannst du den Webhook testen, bevor du ihn in deinem System implementierst. Um einen Webhook zu testen, kannst du eine POST-Anfrage an den Endpunkt /webhooks/{id}/test senden. In dieser Anfrage musst du den resource_id-Parameter angeben, der die ID einer passenden Ressource enthält, die für den Webhook-Typ relevant ist, den du testen möchtest.
Wenn du zum Beispiel einen Webhook für den Typ “Order.created” testen möchtest, musst du eine gültige Order-ID angeben, z.B. “CXY563”. In diesem Fall wird diese Bestellung verwendet, um die Testdaten für den Aufruf zu generieren. Für Testaufrufe ist im Payload unter dem Eintrag 'mode': 'testing' eingetragen. Im Live-Betrieb steht hier 'mode': 'live'.
Wenn du lokal entwickelst, so kannst du z.B. den Anbieter webhook.site verwenden, um die Webhooks dennoch zu empfangen.
Beachte, dass die Testanfrage nur erfolgreich ist, wenn du über die erforderlichen Berechtigungen verfügst und der angegebene Webhook in deinem System gefunden werden kann.
Durch das Testen eines Webhooks kannst du sicherstellen, dass dein System die erwarteten Daten empfängt und korrekt darauf reagiert, bevor du den Webhook in deinem Produktionsumfeld implementierst.