Zum Inhalt springen
Benutzerhandbuch
English한국어DeutschEspañolFrançaisBahasa Indonesia日本語PortuguêsРусскийไทยTiếng Việt简体中文繁體中文

Webhook

Mit Webhooks erhalten Sie Echtzeit-Benachrichtigungen, sobald bestimmte Ereignisse in BoxHero eintreten.

Registrierung

Abschnitt betitelt „Registrierung“

Sie können einen Webhook in Ihrem BoxHero-Team unter Einstellungen > Integrationen registrieren.

Zustellung und Wiederholungsversuche

Abschnitt betitelt „Zustellung und Wiederholungsversuche“

Wenn ein Ereignis eintritt, sendet BoxHero eine HTTP-POST-Anfrage an Ihren registrierten Webhook-Endpunkt. Der Anfragetext enthält eine JSON-Nutzlast, die das Ereignis beschreibt.

  • Antwortet Ihr Server mit einem beliebigen 2xx-Statuscode (z. B. 200, 201, 204), gilt die Zustellung als erfolgreich.
  • Jede Antwort außerhalb des 2xx-Bereichs gilt als Fehlschlag, und die Zustellung wird erneut versucht.

Aufbau der Webhook-Nutzlast

Abschnitt betitelt „Aufbau der Webhook-Nutzlast“

Alle Webhook-Ereignisse werden mit der folgenden JSON-Struktur im Anfragetext zugestellt:

{
  "id": "3f9a2b7c-6d4e-4a1f-9c8b-2e5d7a0f1b34", // Event's unique ID
  "topic": "txs/new", // Event topic
  "version": 1, // Payload schema version
  "payload": { // Event-specific data
    ...
  },
  "created_time": "2025-08-06T09:20:48.623Z" // Timestamp of event occurrence (ISO 8601)
}

Reihenfolge der Ereignisse

Abschnitt betitelt „Reihenfolge der Ereignisse“

BoxHero garantiert die Reihenfolge der Ereigniszustellung nicht. Beispielsweise kann ein item/new-Ereignis nach einem item/delete-Ereignis für denselben Artikel eintreffen.

Das Feld created_time in der Ereignis-Nutzlast gibt den tatsächlichen Zeitpunkt des Ereignisses an. Implementieren Sie in Ihrem Webhook-Handler eine idempotente, reihenfolgeunabhängige Logik, um Ereignisse zuverlässig zu verarbeiten.

Ereignisthemen

Abschnitt betitelt „Ereignisthemen“

txs/new

Abschnitt betitelt „txs/new“

Wird ausgelöst, wenn eine Bestandstransaktion erfolgt (Wareneingang / Warenausgang / Anpassung / Verschieben).

FeldErforderlichBeschreibung
id✓Eindeutige ID der Transaktion
type✓Transaktionstyp
(in, out, adjust, move)
partnerPartner
partner.idEindeutige ID des Partners
partner.nameName des Partners
partner.deletedOb der Partner gelöscht wurde
from_locationAusgangsstandort
from_location.idEindeutige ID des Ausgangsstandorts
from_location.nameName des Ausgangsstandorts
from_location.deletedOb der Ausgangsstandort gelöscht wurde
to_location✓Zielstandort
to_location.id✓Eindeutige ID des Zielstandorts
to_location.name✓Name des Zielstandorts
to_location.deleted✓Ob der Zielstandort gelöscht wurde
items✓Positionen der Transaktion
items.id✓Eindeutige ID des Artikels
items.name✓Artikelname
items.quantity✓Bestandsänderung durch Wareneingang/Warenausgang/Anpassung/Verschieben
items.deleted✓Ob der Artikel gelöscht wurde
items.from_location_new_stock_levelBestand am Ausgangsstandort nach der Transaktion
items.to_location_new_stock_level✓Bestand am Zielstandort nach der Transaktion
transaction_time✓Transaktionszeitpunkt (z. B. Zeitpunkt des Wareneingangs/Warenausgangs)
created_at✓Zeitpunkt, zu dem die Transaktion erstellt wurde
created_by✓Mitglied, das die Transaktion erstellt hat
created_by.id✓Eindeutige ID des Mitglieds
created_by.name✓Name des Mitglieds
created_by.deleted✓Ob das Mitglied gelöscht wurde
count_of_items✓Anzahl der Artikel
total_quantity✓Gesamtmenge der Bestandsänderung
url✓URL der Detailseite der Transaktion
memoNotizen zur Transaktion

Beispiel-Webhook-Nutzlast – Stock In-Ereignis

Abschnitt betitelt „Beispiel-Webhook-Nutzlast – Stock In-Ereignis“
{
  "id": 16160911,
  "type": "in",
  "to_location": {
    "id": 52766,
    "name": "Warehouse 3",
    "deleted": false
  },
  "items": [
    {
      "id": 14277699,
      "name": "belif Cleansing Gel Oil Enriched",
      "quantity": 2,
      "deleted": false,
      "to_location_new_stock_level": 3
    },
    {
      "id": 14277698,
      "name": "belif Aqua Bomb Jelly Cleanser",
      "quantity": 2,
      "deleted": false,
      "to_location_new_stock_level": 5
    }
  ],
  "transaction_time": "2023-04-25T05:42:27.545Z",
  "created_at": "2023-08-14T05:14:29.499Z",
  "created_by": {
    "id": 201345,
    "name": "corp",
    "deleted": false
  },
  "count_of_items": 2,
  "total_quantity": 4,
  "url": "https://web.boxhero-app.com/team/149058/mode/0#/tx/16160911"
}

Beispiel-Webhook-Nutzlast – Move Stock-Ereignis

Abschnitt betitelt „Beispiel-Webhook-Nutzlast – Move Stock-Ereignis“
{
  "id": 3692714,
  "type": "move",
  "from_location": {
    "id": 52765,
    "name": "Warehouse 2",
    "deleted": false
  },
  "to_location": {
    "id": 52766,
    "name": "Warehouse 3",
    "deleted": false
  },
  "items": [
    {
      "id": 14873303,
      "name": "Auto liner 3.5mm",
      "quantity": 1,
      "deleted": false,
      "from_location_new_stock_level": -1,
      "to_location_new_stock_level": 1
    }
  ],
  "transaction_time": "2025-04-25T05:42:27.545Z",
  "created_at": "2025-04-25T05:42:27.545Z",
  "created_by": {
    "id": 176829,
    "name": "Tony Lee",
    "deleted": false
  },
  "count_of_items": 1,
  "total_quantity": 1,
  "url": "https://web.boxhero-app.com/team/150581/mode/2#/ltx/3692714"
}

txs/edit

Abschnitt betitelt „txs/edit“

Wird gesendet, wenn eine bestehende Bestandstransaktion (Wareneingang / Warenausgang / Verschieben / Anpassung) bearbeitet wird.

FeldErforderlichBeschreibung
id✓Eindeutige ID der Transaktion
type✓Transaktionstyp
(in, out, adjust, move)
partnerPartner
partner.idEindeutige ID des Partners
partner.nameName des Partners
partner.deletedOb der Partner gelöscht wurde
from_locationAusgangsstandort
from_location.idEindeutige ID des Ausgangsstandorts
from_location.nameName des Ausgangsstandorts
from_location.deletedOb der Ausgangsstandort gelöscht wurde
to_location✓Zielstandort
to_location.id✓Eindeutige ID des Zielstandorts
to_location.name✓Name des Zielstandorts
to_location.deleted✓Ob der Zielstandort gelöscht wurde
items✓Positionen der Transaktion
items.id✓Eindeutige ID des Artikels
items.name✓Artikelname
items.quantity✓Mengenänderung durch die Transaktion (in/out/adjust/move)
items.deleted✓Ob der Artikel gelöscht wurde
items.from_location_new_stock_levelBestand am Ausgangsstandort nach der Transaktion
items.to_location_new_stock_level✓Bestand am Zielstandort nach der Transaktion
transaction_time✓Transaktionszeitpunkt (z. B. Zeitpunkt des Wareneingangs/Warenausgangs)
created_at✓Zeitpunkt, zu dem die Transaktion erstellt wurde
created_by✓Mitglied, das die Transaktion erstellt hat
created_by.id✓Eindeutige ID des Mitglieds
created_by.name✓Name des Mitglieds
created_by.deleted✓Ob das Mitglied gelöscht wurde
count_of_items✓Anzahl der Artikel
total_quantity✓Gesamtmenge der Bestandsänderung
url✓URL der Detailseite der Transaktion
memoNotizen zur Transaktion
revision✓Aktuelle Versionsnummer der Transaktion, beginnend bei 1

Beispiel-Webhook-Nutzlast – bearbeitete Stock In-Transaktion

Abschnitt betitelt „Beispiel-Webhook-Nutzlast – bearbeitete Stock In-Transaktion“
{
  "id": 16160911,
  "revision": 2,
  "type": "in",
  "to_location": {
    "id": 52766,
    "name": "Warehouse 3",
    "deleted": false
  },
  "items": [
    {
      "id": 14277699,
      "name": "belif Cleansing Gel Oil Enriched",
      "quantity": 2,
      "deleted": false,
      "to_location_new_stock_level": 3
    },
    {
      "id": 14277698,
      "name": "belif Aqua Bomb Jelly Cleanser",
      "quantity": 2,
      "deleted": false,
      "to_location_new_stock_level": 5
    }
  ],
  "transaction_time": "2023-04-25T05:42:27.545Z",
  "created_at": "2023-08-14T05:14:29.499Z",
  "created_by": {
    "id": 201345,
    "name": "corp",
    "deleted": false
  },
  "count_of_items": 2,
  "total_quantity": 4,
  "url": "https://web.boxhero-app.com/team/149058/mode/0#/tx/16160911"
}

Beispiel-Webhook-Nutzlast – bearbeitete Move Stock-Transaktion

Abschnitt betitelt „Beispiel-Webhook-Nutzlast – bearbeitete Move Stock-Transaktion“
{
  "id": 3692714,
  "revision": 2,
  "type": "move",
  "from_location": {
    "id": 52765,
    "name": "Warehouse 2",
    "deleted": false
  },
  "to_location": {
    "id": 52766,
    "name": "Warehouse 3",
    "deleted": false
  },
  "items": [
    {
      "id": 14873303,
      "name": "Auto liner 3.5mm",
      "quantity": 1,
      "deleted": false,
      "from_location_new_stock_level": -1,
      "to_location_new_stock_level": 1
    }
  ],
  "transaction_time": "2023-04-25T05:42:27.545Z",
  "created_at": "2023-04-25T05:42:27.545Z",
  "created_by": {
    "id": 176829,
    "name": "Joy Kim",
    "deleted": false
  },
  "count_of_items": 1,
  "total_quantity": 1,
  "url": "https://web.boxhero-app.com/team/150581/mode/2#/ltx/3692714"
}

txs/delete

Abschnitt betitelt „txs/delete“

Wird gesendet, wenn eine Bestandstransaktion gelöscht wird.

FeldBeschreibung
idEindeutige ID der Transaktion
revisionAktuelle Versionsnummer der Transaktion, beginnend bei 1

Beispiel-Webhook-Nutzlast – gelöschte Transaktion

Abschnitt betitelt „Beispiel-Webhook-Nutzlast – gelöschte Transaktion“
{
  "id": 27036740,
  "revision": 2
}

item/new

Abschnitt betitelt „item/new“

Wird gesendet, wenn dem Bestand des Teams ein neuer Artikel hinzugefügt wird.

FeldBeschreibung
idArtikel-ID
nameArtikelname
skuSKU
barcodeBarcode
photo_urlFoto-URL
costKosten
pricePreis
attrsAttribute

Beispiel-Nutzlast – Artikel erstellt

Abschnitt betitelt „Beispiel-Nutzlast – Artikel erstellt“
{
  "id": 26122826,
  "name": "belif Peat Miracle Revital Cream",
  "sku": "SKU-YH2361KI",
  "barcode": "2002074321218",
  "photo_url": "https://d3l9wd8kivvlqy.cloudfront.net/ap-northeast-2/image-up-ap-northeast-2/30b0cc84-601d-493d-87fd-b7e8b5825601",
  "cost": "50000",
  "price": "65000",
  "attrs": [
    {
      "id": 413101,
      "name": "Category",
      "type": "text",
      "value": "Foundation"
    },
    {
      "id": 459264,
      "name": "Expiration date",
      "type": "date",
      "value": "2027-08-07"
    },
    {
      "id": 668272,
      "name": "Safety Stock",
      "type": "number",
      "value": 33
    }
  ]
}

item/edit

Abschnitt betitelt „item/edit“

Wird gesendet, wenn ein bestehender Artikel bearbeitet wird.

FeldBeschreibung
idArtikel-ID
nameArtikelname
skuSKU
barcodeBarcode
photo_urlFoto-URL
costKosten
pricePreis
attrsAttribute

Beispiel-Nutzlast – Artikel aktualisiert

Abschnitt betitelt „Beispiel-Nutzlast – Artikel aktualisiert“
{
  "id": 26122826,
  "name": "belif Peat Miracle Revital Cream",
  "sku": "SKU-YH2361KI",
  "barcode": "2002074321218",
  "photo_url": "https://d3l9wd8kivvlqy.cloudfront.net/ap-northeast-2/image-up-ap-northeast-2/30b0cc84-601d-493d-87fd-b7e8b5825601",
  "cost": "50000",
  "price": "65000",
  "attrs": [
    {
      "id": 413101,
      "name": "Category",
      "type": "text",
      "value": "Foundation"
    },
    {
      "id": 459264,
      "name": "Expiration date",
      "type": "date",
      "value": "2027-08-07"
    },
    {
      "id": 668272,
      "name": "Safety Stock",
      "type": "number",
      "value": 33
    }
  ]
}

item/delete

Abschnitt betitelt „item/delete“

Wird gesendet, wenn ein Artikel aus dem Bestand des Teams gelöscht wird.

FeldBeschreibung
idArtikel-ID

Beispiel-Nutzlast – Artikel gelöscht

Abschnitt betitelt „Beispiel-Nutzlast – Artikel gelöscht“
{
  "id": 26122826
}