Zum Hauptinhalt springen
Die Integration Webhooks richtet sich an Entwickler. Sie sendet ein JSON-Ereignis an eine HTTPS-Adresse Ihrer Wahl, sobald in Foliant etwas passiert. So kann Ihr eigenes System darauf reagieren, zum Beispiel indem es jede Rechnungs-PDF ablegt oder einen fertigen Export abholt. Webhooks befindet sich in der Beta-Phase. Wenn Sie die Integration unter Einstellungen › Integrationen nicht sehen, ist sie für Ihren Shop noch nicht verfügbar. Wenden Sie sich an den Support, um Zugang anzufragen.

Ereignisse

Webhooks verbinden

  1. Gehen Sie in Foliant zu Einstellungen › Integrationen.
  2. Klicken Sie bei Webhooks auf Verbinden.
  3. Füllen Sie die Einstellungen aus:
  4. Klicken Sie auf Verbinden.
Sie können die URL, den Schlüssel und die Ereignisse später unter Einstellungen auf der Seite der Integration ändern.

Was jede Anfrage enthält

Foliant sendet eine POST-Anfrage mit einem JSON-Body:

Daten von document.generated

  • template: uuid und name der Vorlage.
  • document_type: invoice, credit_note, quote oder leer bei anderen Dokumenten.
  • order: deren id, name und type (Bestellungen oder Bestellentwürfe).
  • refund_id und fulfillment_id, wenn das Dokument zu einer Rückerstattung oder einer Sendung gehört.
  • document_number und issued_at bei nummerierten Dokumenten.
  • source: wie das Dokument erstellt wurde, zum Beispiel download, admin_download, export oder email.
  • export: die ID des Exports, wenn das Dokument Teil eines Exports ist.
  • generated_at.

Daten von export.completed

  • export: dessen uuid, order_type, template_uuids, Anzahl der orders, orders_skipped (nach der Auswahl gelöscht) und documents, requested_by (merchant oder customer) und completed_at.
  • download_url: ein Link zum Herunterladen des Exports, und download_url_expires_at: wann dieser Link nicht mehr funktioniert.
  • download_expires_at: wann der Export selbst abläuft.
Ereignisse enthalten IDs und Anzahlen, keine E-Mail-Adressen von Kunden.

Signatur prüfen

Die Signatur ist ein hexadezimaler HMAC-SHA256 aus dem Zeitstempel, einem Punkt und dem unveränderten Request-Body (<timestamp>.<body>), mit Ihrem Signaturschlüssel als Schlüssel. Berechnen Sie ihn auf Ihrer Seite und vergleichen Sie ihn mit dem Wert nach sha256= in X-Foliant-Signature. Verwenden Sie den Body genau so, wie Sie ihn empfangen haben.

Antworten und Wiederholungen

  • Jede 2xx-Antwort gilt als zugestellt.
  • Wenn Ihr Endpunkt einen 5xx-Fehler, 408 oder 429 zurückgibt oder nicht innerhalb von 10 Sekunden antwortet, versucht Foliant es später erneut, mit jeweils längerer Wartezeit, bis zu 5 Versuche.
  • Andere 4xx-Antworten sind endgültig: Foliant wiederholt sie nicht.
  • Jedes Ereignis wird pro Dokument oder Export einmal zugestellt. Nach einer erfolgreichen Zustellung senden Wiederholungen es nie ein zweites Mal.
Jede Zustellung erscheint unter Aktivität auf der Seite der Integration. Dort können Sie eine fehlgeschlagene Zustellung mit Erneut versuchen wiederholen. Siehe Integrationsaktivität.

Verwandte Artikel