Jak Deel powiadamia
Gdy coś dzieje się na koncie, Deel wysyła POST na adres webhooka z JSON-em, który zawiera typ zdarzenia w data.meta.event_type, organizację, zmieniony zasób i godzinę. Każde doręczenie ma trzy nagłówki: x-deel-signature z podpisem, x-deel-hmac-label, który mówi, jakiego klucza podpisu użyto, oraz x-deel-webhook-version. Webhooki tworzy się przez API, wywołaniem POST /webhooks, albo w zakładce Webhooks w Developer Center, a żeby to zrobić, trzeba być w Deel Org Admin albo IT Developer Admin. Webhook utworzony w sandboksie dostaje tylko zdarzenia z sandboksa.
Jak sprawdza się podpis
Deel liczy HMAC-SHA256 ze słowa POST i następującej po nim treści żądania w niezmienionej postaci, kluczem podpisu webhooka, i prosi, żeby sprawdzić go przed jakimkolwiek przetwarzaniem. Ten klucz (signing_key) Deel zwraca przy tworzeniu webhooka i sam go generuje, jeśli się go nie poda. Jego przykłady kodu dają podpis w zapisie szesnastkowym.
Kontroler konektora liczy to samo kluczem zapisanym w połączeniu, porównuje wynik z x-deel-signature w stałym czasie i odpowiada tak:
| Co dociera do Odoo | Odpowiedź |
|---|---|
| Poprawny podpis | 200, ze zdarzeniem zapisanym w kolejce |
| Brak podpisu albo zły podpis | 401 |
| Nieznany token w adresie albo webhook wyłączony w Odoo | 404 |
| Treść większa niż 1 MB | 413 |
W przeciwieństwie do tokenu API, który przechowuje FlexigoTech Cloud, klucz podpisu zostaje w Odoo, w połączeniu, w polu zarezerwowanym dla administratorów. Testy modułu sprawdzają podpis obliczeniem z przykładu Deel w Pythonie, a utworzenie i usunięcie webhooka przetestowano na demonstracyjnej organizacji Deel.
Jakie są zdarzenia
Strona zdarzeń Deel mówi o ponad 100 («100+ Events») i po pełną listę odsyła do GET /webhooks/events/types, które wymaga uprawnienia webhooks:read. W indeksie dokumentacji referencyjnej API Deel, skopiowanym 18-11-2026, jest 56 zdarzeń z własną stroną. Na tej liście nie ma zdarzenia wystawionej faktury ani raportu brutto-netto: przy fakturach są tylko korekty (Invoice Adjustment Created, Pending For Approval i Reviewed); przy płacach zdarzenia dostępnych pasków wynagrodzeń z Global Payroll i z EOR oraz usuniętego dokumentu płacowego; a przy płatnościach rozpoczęte zestawienie i zestawienie oznaczone jako opłacone.
Konektor subskrybuje 12 z tych zdarzeń, a każde mówi mu tylko, którą część synchronizacji uruchomić:
| Zdarzenia Deel | Co konektor odczytuje ponownie |
|---|---|
payment.statement.initiated, payment.statement.mark-paid | Płatności |
invoice-adjustment.created, invoice-adjustment.reviewed, eor.payslips.available | Faktury |
gp.payslips.available | Płace z Global Payroll |
contract.created, contract.status.updated, contract.terminated, worker.v2.created, worker.v2.updated, worker.v2.deleted | Osoby i umowy |
Zdarzenie, którego konektor nie zna, zostaje zapisane i oznaczone jako wykonane bez uruchamiania czegokolwiek.
Ponowienia i wyłączenie według Deel
Jeśli adres nie odpowie kodem 2xx albo potrzebuje więcej niż 30 sekund, Deel liczy to jako błąd i ponawia po przerwach 1, 2, 4, 8, 16 i 32 minut, potem 1, 2 i 4 godzin, a dziesiąta próba przychodzi po 16 godzinach. Po 10 błędach z rzędu wyłącza subskrypcję, którą trzeba potem ręcznie włączyć, przez API albo w Developer Center. Deel prosi o odpowiedź 200 w ciągu 30 sekund, najlepiej w 5, i ostrzega, że to samo zdarzenie może przyjść więcej niż raz.
Konektor odpowiada, gdy tylko zapisze zdarzenie; synchronizacja przychodzi potem, w kolejce. W Odoo Webhook Aktywny odznacza się tylko przez Usuń webhook albo przez Rozłącz, a konektor nie pyta Deel, w jakim stanie jest webhook. Jeśli Deel wyłączy go po 10 błędach, na przykład dlatego, że Odoo nie działało, Odoo nadal będzie widzieć go jako aktywny: włącza się go ponownie w Developer Center Deel albo usuwa i rejestruje jeszcze raz z Odoo. W tym czasie synchronizacja co 30 minut dalej przynosi te same dane. Żeby sprawdzić, co stało się z każdym doręczeniem, każdy webhook ma w Developer Center zakładkę Logs z kodem, który zwróciło Twoje Odoo; kod 401 wskazuje tam na podpis.
Co robi konektor, gdy dzwoni
Deel wywołuje Twoje Odoo bezpośrednio, pod adresem https z losowym tokenem każdego połączenia, więc FlexigoTech Cloud nie pośredniczy w doręczeniu. Przez FlexigoTech Cloud przechodzą rejestracja i usunięcie webhooka oraz odczyty, które następują potem. Przy poprawnym podpisie Odoo zapisuje w kolejce typ zdarzenia, nie traktując treści jako danych, i budzi zadanie Deel: kolejka webhooków, które poza tym uruchamia się samo co godzinę. To zadanie sprawdza, które części zadzwoniły w każdym połączeniu, i uruchamia każdą tylko raz, nawet jeśli przyszło kilka powiadomień, odczytując dane z Deel ponownie przez API.

Jak zarejestrować go z Odoo
W zakładce Webhooki połączenia administrator klika Zarejestruj webhook. Przycisk pojawia się tylko wtedy, gdy połączenie nie ma już stanu Nie połączone (token jest już zapisany) i webhook nie jest aktywny, a do tego potrzeba:
- żeby Odoo działało na https, bo inaczej konektor się zatrzymuje i przypomina: «Planowana synchronizacja nadal działa bez webhooków.»;
- żeby token miał
webhooks:write, uprawnienie, którego Deel wymaga do utworzenia i do usunięcia webhooka; z tokenem tylko do odczytu Deel odpowiada, według swojego przewodnika po uwierzytelnianiu, kodem 403 albo 401. Przy kodzie 403 konektor pokazuje powód podany przez Deel; przy kodzie 401 podaje, że Deel odrzucił token, i prosi o zapisanie nowego, nawet jeśli tokenowi brakuje tylko tego uprawnienia.
Konektor wysyła do Deel nazwę zaczynającą się od Odoo, adres, 12 zdarzeń z tabeli i wersję v2 API, a następnie zapisuje identyfikator i klucz podpisu zwrócone przez Deel. Jeśli się uda, informuje: «Deel będzie wywoływał Odoo, gdy zmieni się płatność, list płacowy lub kontrakt.» Usuń webhook usuwa go w Deel, podobnie jak Rozłącz, jeśli usługa FlexigoTech Cloud jest aktywna.

Dlaczego co 30 minut i tak wszystko przegląda
Deel zaleca, żeby nie polegać wyłącznie na webhookach i co jakiś czas uzgadniać dane. Konektor robi to zadaniem Deel: synchronizuj kontrakty, faktury, płatności, płace i centra kosztowe, które działa co 30 minut, z webhookami czy bez. I są powody po stronie Deel, żeby go nie wyłączać: na liście Deel nie ma zdarzenia wystawionej faktury, więc nowe faktury przychodzą z tym przeglądem; webhook wyłączony przez Deel nie daje znać Odoo; a Odoo bez https nie może ich odbierać. Z webhookami płatność, pasek wynagrodzenia albo umowa docierają, gdy tylko Deel powiadomi; bez nich przy następnym przejściu.
Co przetestowano
Na demonstracyjnej organizacji Deel (demo.deel.com), za pośrednictwem FlexigoTech Cloud, przetestowano połączenie, podmioty prawne, umowę z jej osobą i dostawcą, webhooki oraz powtórne przejście bez duplikatów. Faktury, płatności i okresy płacowe przetestowano na odpowiedziach przygotowanych na podstawie dokumentacji API Deel, bo ta organizacja jeszcze ich nie miała. Konektor działa w Odoo 17, 18, 19 i 20, na własnym serwerze albo w Odoo.sh, a nie w Odoo Online. Token i jego uprawnienia opisuje poradnik o Deel API token, a to, co trafia do Odoo jako faktura od dostawcy, poradnik o Deel invoice. Konektor jest w pełni opisany na jego stronie i opublikowany w Odoo Apps.
Czytaj dalej
Sprawdzone w kodzie źródłowym konektora (wersja 20.0) i w podlinkowanych źródłach
Źródła
- developer.deel.com/api/webhooks/introduction
- developer.deel.com/api/webhooks/quickstart
- help.letsdeel.com/hc/en-gb/articles/10660690287761-How-To-Create-And-Manage-Webhooks-Notif
- developer.deel.com/api/webhooks/no-code
- developer.deel.com/api/endpoints/webhooks/create-webhook
- developer.deel.com/api/endpoints/webhooks/delete-webhook
- developer.deel.com/api/webhooks/events
- developer.deel.com/api/stable/llms.txt
- developer.deel.com/api/endpoints/webhooks/get-webhook-events
- Kod modułu: flexigo_deel_connector 20.0 (18442307): models/deel_account.py
- Kod modułu: flexigo_deel_connector 20.0 (18442307): controllers/main.py
- Kod modułu: flexigo_deel_connector 20.0 (18442307): data/deel_cron.xml
- Kod modułu: flexigo_deel_connector 20.0 (18442307): static/description/index.html
- Kod modułu: flexigo_deel_connector 20.0 (18442307): tests/test_webhook.py
- developer.deel.com/api/authentication
- apps.odoo.com/apps/modules/20.0/flexigo_deel_connector
- Kod modułu: flexigo_deel_connector 20.0 (18442307): views/deel_account_views.xml
