Webhooki

Dostępne webhooki

merchandise_update_position

Hook wywoływany jest w momencie aktualizacji pozycji towaru.

merchandise_update_status

Hook wywoływany jest w momencie aktualizacji statusu towaru. Hook nie wykona się przy zwykłej aktualizacji towaru, tylko gdy zostanie zmieniony jego status.

---

Dodanie webhooka

W celu dodania webhooka należy zalogować się do panelu klienta TalpaSmart i wejść do zakładki Ustawienia -> Webhooki. Poniżej listy dodanych webhooków należy kliknąć przycisk „Dodaj webhook”.

Na liście webhooków zostanie dodany nowy element, w którym należy uzupełnić 3 informacje:

• Nazwa – nazwa webhooka, która pozwoli go łatwiej odnaleźć.
• Typ zdarzenia – wybieramy typ zdarzenia, do którego webhook ma zostać dodany (można wybrać więcej niż jedną opcję).
• URL – adres URL, na który mają zostać wysłane informacje przez webhook.

Domyślnie webhook jest aktywny, ale można go wyłączyć, przełączając kontrolkę znajdującą się po prawej stronie od adresu URL webhooka.

Po uzupełnieniu powyższych danych należy kliknąć przycisk „Zapisz” znajdujący się w prawym górnym rogu karty.

---

Odbieranie webhooka

Webhooki są wysyłane metodą POST, a wraz z informacją dotyczącą danego webhooka jest przesłany również nagłówek X-HMAC zawierający wyliczoną sumę kontrolną z przesyłanej wiadomości.

Sprawdzanie sumy kontrolnej

Skrypt odbierający wiadomość, po poprawnym odebraniu musi zwrócić status 200. W innym przypadku request zostanie oznaczony jako nieodebrany i będzie następowała próba jego ponowienia (ponawianie webhooków).

**Payload:**
```json
{
    "meta": {
        "type": "<webook_type>"
    },
    "data": "<webook_data>"
}

• <webook_type> – zawiera informację o typie webhooka.
• <webook_data> – zawiera dane dotyczące webhooka. W zależności od typu różnią się one polami.

merchandise_update_position

Request będzie zawierał 3 informacje:

• merchandise – identyfikator towaru w systemie.
• lat – szerokość geograficzna nowej pozycji.
• lon – długość geograficzna nowej pozycji.

Przykład:

{
    "meta": {
        "type": "merchandise_update_position"
    },
    "data": {
        "merchandise": "12",
        "lat": 52.229675,
        "lon": 21.012230
    }
}

merchandise_update_status

Request będzie zawierał 2 informacje:

• merchandise – identyfikator towaru w systemie.
• status – nowy status towaru.

Pole status zawiera jedną z poniższych wartości:

• at_the_customer – Towar u klienta.
• ready_to_return – Gotowy do odbioru.
• returned – Zwrócony.

{
    "meta": {
        "type": "merchandise_update_status"
    },
    "data": {
        "merchandise": "12",
        "status": "ready_to_return"
    }
}

Sprawdzanie sumy kontrolnej

W panelu, nad listą webhooków znajduje się „Webhook secret”. Jest to klucz potrzebny do weryfikacji poprawności danych.

Do wyliczenia sumy kontrolnej używana jest funkcja HMAC-SHA256. Uzyskaną sumę kontrolną należy porównać z wartością znajdującą się w nagłówku X-HMAC. Jeżeli suma kontrolna nie pokrywa się z przesłaną w nagłówku, należy taką wiadomość odrzucić.

• secret – Webhook secret odczytany z aplikacji.
• payload – Treść wiadomości odebranej z webhooka.

PHP

<?php
echo hash_hmac('sha256', $payload, $secret);

Python

import hmac
import hashlib

dig = hmac.new(secret, msg=payload, digestmod=hashlib.sha256).digest()
print(dig)

Ponawianie webhooków

Jeżeli skrypt odbierający request webhooka nie zwróci kodu statusu 200, webhook będzie próbował go ponowić. Próba ponownego przesłania webhooka odbywa się co 1h, maksymalnie 100 razy. Jeżeli request nie zostanie odebrany po 100 próbach, taki request zostanie usunięty.