Zum Inhalt

Anleitung zur Webhook-Integration

Gift Card Hero sendet HTTP-POST-Anfragen an Ihren Server, sobald bestimmte Ereignisse rund um Geschenkgutscheine eintreten. Verwenden Sie Webhooks, um externe Systeme in Echtzeit mit der Geschenkgutschein-Aktivität synchron zu halten.

Einrichtung

  1. Gehen Sie in der linken Navigation zu For developers.
  2. Setzen Sie das Häkchen bei Enable REST API und speichern Sie. Die Webhook-Einstellungen erscheinen nur, solange die REST API aktiviert ist.
  3. Klicken Sie auf Generate Secret, um einen Signaturschlüssel für Webhooks zu erstellen.

Erstellung des Webhook-Geheimschlüssels

Der Schlüssel wird nur einmal angezeigt

Kopieren Sie den Schlüssel und bewahren Sie ihn sicher auf. Falls Sie ihn verlieren, klicken Sie auf Regenerate Secret, um einen neuen zu erstellen. Der alte Schlüssel funktioniert sofort nicht mehr, aktualisieren Sie daher auch Ihren Server.

  1. Geben Sie für jeden Webhook-Typ, den Sie empfangen möchten, Ihre Endpunkt-URLs ein und klicken Sie dann in der Speicherleiste auf Save.

Webhook-Endpunkt-URLs

Eine neue oder geänderte Endpunkt-URL muss mit https:// beginnen und auf einen aus dem Internet erreichbaren Server verweisen. Adressen aus einem privaten Netzwerk, also localhost, 127.0.0.1, 10.x.x.x, 192.168.x.x und ähnliche, werden beim Speichern abgelehnt. Eine URL, die vor dieser Regel gespeichert wurde, funktioniert weiter, bis Sie sie ändern, wird aber nur aufgerufen, wenn sie auf eine öffentliche Adresse zeigt. Um gegen einen lokalen Server zu testen, machen Sie ihn über einen Tunnel wie ngrok erreichbar und verwenden Sie die öffentliche https-URL, die er Ihnen gibt.

Ereignistypen

Gift Card Hero hat drei Felder für Webhook-URLs:

Ereignis Wert des Topic-Headers Wann es ausgelöst wird
Gift card order gift_card_order Gift Card Hero verarbeitet die Geschenkgutscheine einer Bestellung. Die Payload listet die Karten auf, die zur Bestellung gehören
Gift card payment gift_card_payment Eine Bestellung wird erstellt, die ganz oder teilweise mit einem Geschenkgutschein bezahlt wurde
Gift card balance change gift_card_balance Derzeit nicht gesendet

Webhook für Guthabenänderungen

Das Feld Gift card balance webhook URL ist auf der Seite vorhanden, aber Gift Card Hero sendet dieses Ereignis noch nicht. Um Guthabenänderungen heute zu verfolgen, fragen Sie GET /gift-cards/transactions ab oder verwenden Sie für Zahlungen das Ereignis gift_card_payment.

Webhooks werden nur gesendet, solange Enable REST API aktiviert ist und die URL für das jeweilige Ereignis ausgefüllt ist.

Zustellung

  • Methode: POST
  • Timeout: 6 Sekunden
  • Versuche: Insgesamt bis zu 5 Zustellversuche (der erste und bis zu 4 Wiederholungen), mit exponentiell wachsenden Wartezeiten, die bei etwa 30 bis 60 Sekunden beginnen
  • Weiterleitungen: Werden nicht verfolgt. Eine 3xx-Antwort gilt als fehlgeschlagene Zustellung, verwenden Sie daher die endgültige URL Ihres Endpunkts.

Wenn Ihr Endpunkt nicht innerhalb von 6 Sekunden eine 2xx-Antwort zurückgibt, gilt die Zustellung als fehlgeschlagen und wird erneut versucht.

Header

Jede Webhook-Anfrage enthält die folgenden Header:

Header Wert
Content-Type application/json
User-Agent GiftHero-Webhooks/1.0
X-GiftHero-Topic Der Ereignistyp (z. B. gift_card_order)
X-GiftHero-Signature HMAC-SHA256-Signatur zur Prüfung. Wird nur gesendet, wenn Sie einen Webhook-Signaturschlüssel erzeugt haben

Signaturprüfung

Der Header X-GiftHero-Signature enthält eine HMAC-SHA256-Signatur, hexadezimal kodiert und mit sha256= beginnend.

Wichtig: Die Signatur wird über ein JSON-Objekt berechnet, das nur { type, timestamp } aus dem Body der Payload enthält, NICHT über den gesamten Request-Body.

Prüfschritte

  1. Parsen Sie den Request-Body und extrahieren Sie die Felder type und timestamp
  2. Erstellen Sie die Signatur-Payload: JSON.stringify({ type, timestamp })
  3. Berechnen Sie die HMAC-SHA256 mit Ihrem Webhook-Signaturschlüssel als Schlüssel
  4. Kodieren Sie das Ergebnis hexadezimal und stellen Sie sha256= voran
  5. Vergleichen Sie es mit dem Header X-GiftHero-Signature über einen zeitkonstanten Vergleich

Beispiel (Node.js)

const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const signingPayload = JSON.stringify({
    type: body.type,
    timestamp: body.timestamp
  });

  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(signingPayload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Payload-Schemas

Jeder Request-Body hat dieselbe Hülle. Die Details des Ereignisses stehen in data:

{
  "type": "gift_card_order",
  "timestamp": "2026-03-15T10:30:00.000Z",
  "data": { }
}

Geschenkgutschein-Bestellung (gift_card_order)

{
  "type": "gift_card_order",
  "timestamp": "2026-03-15T10:30:00.000Z",
  "data": {
    "order": {
      "id": 5551234567890,
      "name": "#1042",
      "email": "buyer@example.com",
      "createdAt": "2026-03-15T10:30:00.000Z",
      "lineItems": [
        {
          "id": 11198765432100,
          "title": "Gift Card",
          "quantity": 1,
          "sku": "GC-50",
          "variantId": 44556677
        }
      ]
    },
    "giftCards": [
      {
        "id": 987654321,
        "balance": "50.00",
        "currency": "USD",
        "lastCharacters": "ab12",
        "initialValue": "50.00",
        "customer": { "id": 123, "email": "buyer@example.com", "name": "Alex Buyer" },
        "recipient": { "id": 456, "email": "friend@example.com", "name": "Sam Friend" },
        "code": "abcd1234efgh5678",
        "lineItemId": 11198765432100,
        "sku": "GC-50"
      }
    ]
  }
}

Geschenkgutschein-Zahlung (gift_card_payment)

Jeder Eintrag in giftCards enthält außerdem die transaction, mit der die Bestellung bezahlt wurde.

{
  "type": "gift_card_payment",
  "timestamp": "2026-03-16T14:22:00.000Z",
  "data": {
    "order": {
      "id": 5551234567891,
      "name": "#1043",
      "email": "shopper@example.com",
      "createdAt": "2026-03-16T14:22:00.000Z",
      "lineItems": [
        { "id": 11198765432200, "title": "Running Shoes", "quantity": 1, "sku": "SHOE-9" }
      ]
    },
    "giftCards": [
      {
        "id": 987654321,
        "balance": "0.00",
        "currency": "USD",
        "lastCharacters": "ab12",
        "initialValue": "50.00",
        "customer": null,
        "recipient": null,
        "transaction": {
          "id": "gid://shopify/OrderTransaction/123456789",
          "amount": "50.00",
          "currency": "USD",
          "type": "debit",
          "createdAt": "2026-03-16T14:22:00.000Z"
        }
      }
    ]
  }
}

Feldhinweise

  • data.order und data.giftCards sind die Felder, auf die Sie aufbauen sollten. data wiederholt außerdem einige Bestellfelder auf oberster Ebene (orderId, orderName, orderEmail, createdAt, lineItems) und enthält interne Felder (storeId, shop, jobType). Verlassen Sie sich nicht auf diese.
  • balance ist das Guthaben der Karte zum Zeitpunkt, zu dem der Webhook erstellt wird, nicht zum Zeitpunkt der Bestellung.
  • code ist der vollständige Geschenkgutschein-Code. Er ist nur enthalten, wenn Gift Card Hero den Code gespeichert hat, und sonst weggelassen. Behandeln Sie ihn wie ein Passwort und stellen Sie sicher, dass Ihr Endpunkt gesichert ist.
  • lineItemId und sku sind enthalten, wenn die Karte einer Bestellposition zugeordnet werden kann.
  • Einträge in lineItems enthalten id, title, quantity, sku und variantId (ohne Preis).
  • Wenn die Details einer Karte nicht geladen werden können, wird ihr Eintrag auf id, Nullbeträge und ein leeres lastCharacters reduziert. Lesen Sie die Karte in diesem Fall über die REST API erneut ein.

Bewährte Methoden

  • Schnell mit 2xx antworten: Bestätigen Sie den Webhook sofort und verarbeiten Sie die Payload asynchron. Antworten, die länger als 6 Sekunden dauern, gelten als Fehler.
  • Duplikate behandeln: Dasselbe Ereignis kann aufgrund von Wiederholungen mehrfach zugestellt werden. Verwenden Sie die Bestell- und Geschenkgutschein-IDs in den Ereignisdaten zur Deduplizierung. Der timestamp ist der Zeitpunkt jedes Versuchs und daher kein stabiler Schlüssel.
  • HMAC-Signaturen prüfen: Prüfen Sie den Header X-GiftHero-Signature immer, bevor Sie eine Webhook-Payload verarbeiten. Lehnen Sie Anfragen mit ungültigen Signaturen ab.
  • Idempotenz sicherstellen: Gestalten Sie Ihren Webhook-Handler idempotent, sodass die doppelte Verarbeitung desselben Ereignisses dasselbe Ergebnis liefert.
  • Fehler überwachen: Schlägt Ihr Endpunkt dauerhaft fehl, stoppt Gift Card Hero die Wiederholungen nach insgesamt 5 Versuchen. Prüfen Sie Ihre Serverprotokolle und den Zustand des Endpunkts regelmäßig.