Transformationen

Transformationen erlauben es Ihnen, JavaScript-Code zu schreiben, der Webhook-Eigenschaften modifiziert, bevor sie an Ihren Endpoint zugestellt werden. Sie können die HTTP-Methode, die Ziel-URL, die Payload oder benutzerdefinierte Header ändern oder bestimmte Webhooks sogar abbrechen.

Anwendungsfälle

Transformationen sind nützlich, wenn Sie:

Payloads anpassen, um dem erwarteten Format Ihres Systems zu entsprechen
Webhooks umleiten an unterschiedliche URLs je nach Payload-Inhalt
Benutzerdefinierte Header hinzufügen für Authentifizierung oder Routing
Webhooks filtern, indem Sie nicht benötigte abbrechen
Daten transformieren (z. B. Währungsformate konvertieren, Felder umbenennen)

Zugriff auf Transformationen

Öffnen Sie die Webhook-Einstellungen in Ihrem Dashboard
Klicken Sie auf einen Endpoint, um dessen Details anzuzeigen
Wechseln Sie zum Tab Advanced
Scrollen Sie zur Karte Transformations
Aktivieren Sie den Schalter, um Transformationen zu aktivieren

Eine Transformation schreiben

Transformationen verwenden eine JavaScript-Funktion handler, die die Webhook-Daten erhält und die modifizierte Version zurückgibt.

Eingabeeigenschaften

Die Funktion handler erhält ein Objekt mit diesen Eigenschaften:

Eigenschaft	Typ	Beschreibung
`method`	string	HTTP-Methode (`"POST"` oder `"PUT"`)
`url`	string	Die Endpoint-URL
`payload`	object	Die Webhook-Payload als JSON
`eventType`	string	Der Event-Typ (schreibgeschützt)

Rückgabeeigenschaften

Geben Sie dasselbe Objekt mit Ihren Änderungen zurück. Sie können außerdem hinzufügen:

Eigenschaft	Typ	Beschreibung
`cancel`	boolean	Auf `true` setzen, um diesen Webhook abzubrechen
`headers`	object	Benutzerdefinierte Header, die dem Request hinzugefügt werden

Beispiele

Payload modifizieren

Verschachtelte Daten flach machen oder Felder umbenennen:

function handler(webhook) {
  // Add a custom field
  webhook.payload.source = "storekit";
  
  // Rename a field
  webhook.payload.orderId = webhook.payload.order_id;
  delete webhook.payload.order_id;
  
  return webhook;
}

Basierend auf Payload umleiten

Webhooks je nach Inhalt an unterschiedliche URLs senden:

function handler(webhook) {
  if (webhook.payload.priority === "high") {
    webhook.url = "https://example.com/webhooks/priority";
  }
  return webhook;
}

Benutzerdefinierte Header hinzufügen

Zusätzliche Header für Ihren Endpoint einfügen:

function handler(webhook) {
  webhook.headers = {
    "X-Custom-Header": "my-value",
    "X-Store-ID": webhook.payload.store_id
  };
  return webhook;
}

Bestimmte Webhooks abbrechen

Filtern Sie Webhooks heraus, die Sie nicht empfangen möchten:

function handler(webhook) {
  // Don't send webhooks for test orders
  if (webhook.payload.test_mode === true) {
    webhook.cancel = true;
  }
  return webhook;
}

HTTP-Methode ändern

Von POST zu PUT wechseln, falls benötigt:

function handler(webhook) {
  webhook.method = "PUT";
  return webhook;
}