Etsy-API-Webhooks → Push-Benachrichtigung aufs Handy

Was Etsys Webhooks wirklich liefern

Jahrelang war Polling von getShopReceipts der einzige Weg, von einem Etsy-Verkauf zu erfahren. Das hat sich geändert: Im Dezember 2025 hat Etsy Webhooks für kommerzielle Apps ausgerollt, am 17. Februar 2026 kam der volle Zugang für persönliche Anwendungen dazu. Vier Events gibt es, jedes wird sofort zugestellt:

• order.paid – eine Bestellung wurde bezahlt
• order.canceled – der Verkäufer storniert eine Bestellung
• order.shipped – zu einem Beleg wurden Versandinfos angelegt
• order.delivered – eine Bestellung gilt als zugestellt

Der entscheidende Punkt, der die meisten überrascht: Das Payload ist winzig. Jedes Event – egal welcher Typ – enthält genau drei Felder:

{
  "event_type": "order.paid",
  "resource_url": "https://openapi.etsy.com/v3/application/shops/12345/receipts/67890",
  "shop_id": 12345
}

Kein Käufer, kein Artikelname, kein Preis. Etsy sagt dir dass etwas passiert ist und gibt dir eine URL, um zu fragen was. Genau diese Design-Entscheidung macht den nächsten Abschnitt so kurz.

Die Zwei-Minuten-Variante: ganz ohne Server

Ein Webhooky-Endpunkt ist nichts anderes als eine URL, die einen HTTP-POST annimmt und daraus eine Push-Benachrichtigung macht. Etsy braucht „eine öffentlich erreichbare Callback-URL, die POST-Requests annimmt“. Diese beiden Hälften passen direkt zusammen:

1. Lege in der Webhooky-App einen Endpunkt an. Nenn ihn Etsy-Verkauf, setz als Nachricht z. B. „Jemand hat in deinem Shop gekauft“ und wähl den Sound cash_register oder ka_ching. URL kopieren.
2. Öffne in Etsys Developer Portal den Punkt Manage your apps, klapp das Dropdown deiner App auf und wähl Go to Webhook portal.
3. Auf +Add Endpoint klicken, die Webhooky-URL einfügen, order.paid auswählen und auf Create.

Fertig. Etsy schickt seine drei Felder, Webhooky ignoriert sie, und weil title und message fehlen, greift der Fallback auf Titel und Text, die du am Endpunkt eingestellt hast. Du bekommst pro Verkauf eine sofortige Benachrichtigung mit eigenem Klang – auf allen Geräten, auf denen du angemeldet bist.

Zwei Dinge solltest du wissen, bevor du dich darauf verlässt:

• Webhooky prüft Etsys Signatur nicht. Etsy signiert jede Zustellung mit den Headern webhook-id, webhook-timestamp und webhook-signature, ein einfacher Webhooky-Endpunkt nimmt aber jeden POST an. Wer deine URL kennt, kann eine Benachrichtigung auslösen. Bei einem Verkaufs-Ping ist das schlimmstenfalls lästig – wenn es dir wichtig ist, nimm den Backend-Weg weiter unten.
• Etsy wiederholt hartnäckig. Fehlgeschlagene Zustellungen werden sofort erneut versucht, dann nach 5 Sekunden, 5 Minuten, 30 Minuten, 2 Stunden, 5 Stunden, 10 Stunden und noch einmal nach 10 Stunden. Webhooky antwortet immer mit 200, auch wenn du das Limit des Gratis-Tarifs erreicht hast – du landest also nie in einem Retry-Sturm.

Wenn du Artikelname und Preis willst

Die Benachrichtigung oben sagt „ein Verkauf ist passiert“. Für „Handgetöpferte Tasse · 34,00 €“ muss jemand resource_url aufrufen, und dieser Aufruf braucht dein OAuth-2.0-Access-Token – muss also dort passieren, wo du die Kontrolle hast. Nimm Etsys Webhook in deiner eigenen Function entgegen, reichere ihn an und schick dann einen POST mit explizitem title und message an Webhooky:

export async function onEtsyWebhook(req, res) {
  res.sendStatus(200);                       // erst quittieren, dann arbeiten

  const { event_type, resource_url } = req.body;
  if (event_type !== "order.paid") return;

  const receipt = await fetch(resource_url, {
    headers: {
      "x-api-key": process.env.ETSY_KEYSTRING,
      Authorization: `Bearer ${await etsyAccessToken()}`,
    },
  }).then((r) => r.json());

  const item = receipt.transactions?.[0]?.title ?? "ein Artikel";
  const total = receipt.grandtotal;

  await fetch(process.env.WEBHOOKY_URL, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      title: "🧶 Etsy-Verkauf!",
      message: `${item} · ${total.amount / total.divisor} ${total.currency_code}`,
      sound: "cash_register",
    }),
  });
}

Erst quittieren, dann anreichern – Etsys Retry-Plan bestraft langsame Endpunkte, und ein Beleg-Abruf plus Push ist leicht langsamer als das Zustell-Timeout.

Signatur prüfen

Wenn du den Backend-Weg gehst: erst prüfen, dann vertrauen. Etsys Verfahren ist symmetrisches Standard-Signing. Bau webhook-id + "." + webhook-timestamp + "." + raw_body aus dem rohen Body, bevor irgendein JSON geparst wird. Entferne das Präfix whsec_ aus deinem Signing-Secret und dekodiere den Rest Base64. Berechne HMAC-SHA256 über den signierten Inhalt mit diesem Schlüssel und kodiere das Ergebnis Base64. Akzeptiere, wenn es zu einem Eintrag in webhook-signature passt. Verwirf alles, dessen webhook-timestamp mehr als 300 Sekunden von deiner Uhr abweicht, damit ein alter Mitschnitt nicht erneut eingespielt werden kann.

Kein Entwickler? Nimm Zapier, Make oder IFTTT

Etsys Webhook-Portal hängt hinter einer Developer-App, und das ist mehr Aufwand, als die meisten Verkäufer wollen. Jedes größere Automatisierungs-Tool hat eine offizielle Etsy-Integration, die diesen Teil übernimmt:

1. Webhooky-Endpunkt anlegen und URL kopieren, wie oben.
2. Einen Zap mit dem Trigger Etsy → New Transaction bauen (in Make und IFTTT „New Order“).
3. Die Aktion Webhooks → POST hinzufügen, deinen Link einfügen und ein JSON senden:

{
  "title": "🧶 Etsy-Verkauf!",
  "message": "{{title}} · {{price}} {{currency}}"
}

Weil der Trigger die Bestelldaten schon enthält, bekommst du Artikel und Preis, ohne etwas zu schreiben oder zu hosten. Der Preis dafür ist Latenz: Diese Integrationen fragen Etsy nach Zeitplan ab, rechne also mit Minuten statt Sekunden – und mit einem Task-Kontingent in den Gratis-Tarifen.

Welcher Weg passt?

• Etsy-Webhook direkt auf Webhooky – Sekunden, keine Infrastruktur, keine Bestelldetails, keine Signaturprüfung. Ideal für „sag mir sofort, wenn etwas verkauft wird“.
• Etsy-Webhook → deine Function → Webhooky – Sekunden, volle Bestelldetails, Signatur geprüft. Ideal, wenn du ohnehin ein Backend betreibst.
• Zapier / Make / IFTTT – Minuten, volle Bestelldetails, kein Code. Ideal, wenn du Verkäufer bist und nicht Entwickler.

Weitere Etsy-Signale, die sich lohnen

Sobald ein Endpunkt existiert, erreicht dich alles, was einen POST senden kann. order.shipped und order.delivered stehen schon in Etsys Event-Liste. Über ein Automatisierungs-Tool kommen eine neue Bewertung dazu, eine Warnung bei niedrigem Lagerstand, bevor ein Artikel inaktiv wird, oder ein neuer Favorit auf einem bewusst leiseren Sound. Gib jedem Signal einen eigenen Endpunkt und einen eigenen Klang, dann unterscheidest du sie, ohne hinzusehen.

Warum nicht einfach die Etsy-Seller-App?

Kannst du – die meisten Verkäufer nutzen beides. Etsys App ist zum Verwalten des Shops da, Webhooky zum Hören. Jedes Ereignis bekommt eigenen Sound und eigenes Vibrationsmuster, Benachrichtigungen kommen auf allen Geräten gleichzeitig an, und jeder Endpunkt führt seine eigene Historie, durch die du zurückscrollen kannst. Es gibt kein Konto anzulegen – installieren, Endpunkt erstellen, fertig.