Webhooki wychodzące

Zamiast odpytywać Kangura co minutę, każ mu powiadamiać Twój system o tym, co się wydarzyło.

Jak to podłączyć

Ustawienia → Webhooki → Dodaj → podaj adres HTTPS i zaznacz zdarzenia. Każda subskrypcja ma własny sekret — służy do sprawdzenia, że żądanie naprawdę pochodzi od Kangura.

Weryfikacja podpisu

Każde żądanie niesie nagłówek X-Kangur-Signature — to HMAC-SHA256 treści żądania, policzony sekretem subskrypcji, zapisany szesnastkowo.

import hashlib, hmac, json

def podpis_sie_zgadza(tresc: bytes, naglowek: str, sekret: str) -> bool:
    oczekiwany = hmac.new(sekret.encode(), tresc, hashlib.sha256).hexdigest()
    return hmac.compare_digest(oczekiwany, naglowek)   # NIE zwykłe ==

Porównuj podpisy funkcją odporną na pomiar czasu

Zwykłe == przerywa porównanie na pierwszej różnicy, co pozwala odgadywać podpis po czasie odpowiedzi. Użyj hmac.compare_digest (Python), crypto.timingSafeEqual (Node) albo odpowiednika w swoim języku.

Zdarzenia

Te same nazwy, których używają automatyzacje. Pełną, zawsze aktualną listę zwraca GET /api/webhooks/events — poniżej ta sama lista w komplecie:

• Zamówienia — order.created, order.updated, order.status_changed, order.category_assigned, order.category_released, order.category_ack_required, order.category_acknowledged, order.paid, order.shipped, order.fulfilled
• Kompletacja i pakowanie — order.picking_started, order.picked, order.picking_cancelled, order.packing_started, order.packed, order.packing_cancelled
• Produkty i magazyn — product.created, product.updated, product.stock_changed, product.price_changed, product.cost_changed, stock.low_alert
• Przesyłki — shipment.created, shipment.status_changed
• Przesyłki przychodzące — inbound.received (przyjęcie dostawy, zwrotu lub przesunięcia na magazyn; PZ powstaje jako szkic)
• Zwroty — return.created, return.status_changed, return.refunded

Zanim uznasz, że działa

POST /api/webhooks/{id}/test wysyła próbne żądanie pod Twój adres. GET /api/webhooks/{id}/deliveries pokazuje historię doręczeń wraz z kodem odpowiedzi Twojego serwera — to pierwsze miejsce, w które warto zajrzeć, gdy „nic nie przychodzi”.

Po Twojej stronie

• Odpowiadaj szybko (2xx) i przetwarzaj w tle. Długa odpowiedź to ryzyko przeterminowania.
• Licz się z powtórzeniem. Sieć bywa zawodna; to samo zdarzenie może dojść dwa razy. Zapisuj identyfikator zdarzenia i pomijaj duplikaty.
• Nie zakładaj kolejności. Zdarzenia mogą dotrzeć w innej kolejności, niż zaszły.

Webhooki przychodzące

Odwrotny kierunek — powiadomienia od platform sprzedażowych do Kangura — konfigurujesz przy każdej integracji z osobna. Adres i sekret znajdziesz w Ustawienia → Integracje po wybraniu konkretnego połączenia.