Przejdź do treści

Automatyzacja zatwierdzeń w Zapier, Make i n8n: przepis na webhook

Zarejestruj webhook DueReason: zweryfikuj HMAC i podłącz approval.approved/executed w Zapierze, Make i n8n, by automatyzować zatwierdzenia bez kodu.

Aktualizacja · 13 min czytania

W skrócie

  • Webhook DueReason niesie już wszystko, czego potrzebuje narzędzie bez kodu: zarejestruj jeden endpoint, wybierz approval.approved i approval.executed, i zweryfikuj podpis HMAC, zanim zaufasz danym.
  • Webhook mówi, że zapadła decyzja; nie daje gotowego poświadczenia do działania. Zaraz po approval.approved pobierz wniosek, żeby odczytać jego grant, i nie pomijaj tego kroku w swoim przepływie.
  • Węzeł Webhook w n8n, Catch Raw Hook w Zapierze i moduł Custom webhook w Make potrafią zachować dokładną surową treść, jakiej potrzebuje weryfikacja podpisu — jeśli włączysz tę opcję.
  • Zamknij pętlę: gdy przepływ wykona akcję z grantem, wywołaj POST /approvals/{id}/executions. DueReason zapisuje przedstawiony grant i wysyła approval.executed razem z nim, więc ślad audytowy pokazuje, co upoważniło działanie.
  • Poniżej trzy gotowe przykłady podłączają tę samą pętlę do konkretnego działania: odebrania dostępu w Okta lub Google Workspace, wysłania umowy do podpisu w DocuSign lub PandaDoc oraz utworzenia faktury kosztowej w Xero lub QuickBooks po zatwierdzeniu płatności.

Webhook DueReason już teraz wysyła wszystko, czego potrzebuje narzędzie bez kodu: podpisaną, ponawianą wysyłkę na każdym etapie zatwierdzenia, łącznie z momentem decyzji i momentem, w którym ktoś zgłasza, że z niej skorzystał. Ten przepis rejestruje endpoint, weryfikuje podpis bez własnego serwera i podłącza approval.approved oraz approval.executed do n8n, Zapiera albo Make, tak by przepływ mógł zadziałać i zgłosić wynik, a nie tylko powiadomić.

Co naprawdę jest w danych

Każda wysyłka to JSON z polami id, type, createdAt i data; data zawsze niesie requestId i seq, a do tego pola właściwe danemu zdarzeniu. Dla automatyzacji liczą się dwa zdarzenia:

Poleapproval.approvedapproval.executed
grantIdid grantuid grantu
grantnieobecnepodpisany grant (JWS), który przedstawiono
approverskto zdecydował—
outcome—succeeded albo failed
detail—dowolny tekst, np. id płatności lub wdrożenia

approval.approved mówi, że wniosek został rozstrzygnięty; nie niesie grantu gotowego do użycia. Grant to podpisane, jednorazowe poświadczenie związane z dokładnie tym ładunkiem, a DueReason podpisuje je na nowo przy każdym odczycie zamiast je przechowywać, więc Twój przepływ pobiera je przez GET /approvals/{id} zaraz po webhooku, kluczem API ze scope'em approval:read. approval.executed, w odróżnieniu, niesie grant, bo w tym momencie jest on już zużyty: to ten sam grant, który Twój przepływ (albo cokolwiek wykonało akcję) przedstawił, zgłaszając wynik — zapisany jako dowód, co upoważniło wykonanie, a nie coś, czym można zadziałać ponownie.

Zarejestruj webhook w DueReason

W Ustawieniach, Webhooks, dodaj adres HTTPS swojego endpointu i wybierz approval.approved oraz approval.executed (albo * dla wszystkiego). Sekret podpisujący, whsec_..., pokazuje się tylko raz; przechowaj go tam, gdzie Twój przepływ trzyma poświadczenia, nigdy wprost w eksporcie JSON przepływu. Po zmianie sekretu każde dostarczenie wysłane od tej chwili jest podpisane nowym; poprzedni pozostaje widoczny w Ustawieniach przez 24 godziny, więc nadal sprawdzisz dostarczenia podpisane przed zmianą, zanim zaktualizujesz przepływ.

Zweryfikuj podpis, zanim mu zaufasz

Nagłówek DueReason-Signature wygląda tak: t=1730000000,v1=3f29a1... — t to czas Unix podpisania, v1 to szesnastkowy HMAC-SHA256 ze znacznika czasu, kropki i surowej treści żądania, w tej kolejności, kluczem Twojego endpointu — nie wartości, którą Twoje narzędzie na nowo zserializowało z własnego sparsowanego JSON-a, bo to zmienia kolejność kluczy i białe znaki i psuje porównanie. Przelicz ten sam HMAC ze znacznika czasu i surowej treści, porównaj go z v1 w stałym czasie i odrzuć wszystko, gdzie znacznik czasu różni się od teraz o więcej niż pięć minut. Pełny przykład w Node.js w dokumentacji API pokazuje dokładnie tę samą weryfikację, jaką uruchomiłby Twój własny serwer; każdy przepis poniżej to te same cztery kroki w narzędziu bez kodu.

Zbuduj to w n8n

  1. Dodaj węzeł Webhook: metoda POST, a w jego opcjach włącz Raw Body, żeby węzeł zachował nieparsowane bajty obok sparsowanego JSON-a. Wklej Production URL do ustawień webhooka w DueReason.
  2. Dodaj węzeł Code, który odczytuje nagłówek podpisu i surową treść z przychodzącego żądania, liczy HMAC wbudowanym modułem crypto Node.js (dostępnym wewnątrz węzła Code) i rzuca błąd, gdy nie zgadza się z v1 albo znacznik czasu jest nieaktualny. Nieudana weryfikacja powinna zatrzymać przepływ, a nie tylko zostać zalogowana.
  3. Dodaj węzeł Switch na {{$json.body.type}}: jedna gałąź dla approval.approved, druga dla approval.executed.
  4. Na gałęzi approved dodaj węzeł HTTP Request z poświadczeniem HTTP Bearer Auth trzymającym Twój klucz API DueReason, wywołujący GET /approvals/{{$json.body.data.requestId}}, żeby odczytać jego grant. Przekaż ten grant do węzła, który wykonuje Twoją akcję.
  5. Po wykonaniu akcji dodaj drugi węzeł HTTP Request, POST /approvals/{{requestId}}/executions, treść { "grant": ..., "outcome": "succeeded", "detail": ... }, żeby zarówno zapis w DueReason, jak i kolejna wysyłka approval.executed, to pokazały.

Zbuduj to w Zapierze

Zwykły trigger Catch Hook w Zapierze parsuje treść za Ciebie, co akurat psuje weryfikację podpisu: zmieniona kolejność kluczy daje inny HMAC niż ten, który policzył DueReason. Użyj zamiast niego Catch Raw Hook (Webhooks by Zapier), który zachowuje nieparsowaną treść i nagłówki żądania dla kolejnych kroków.

  1. Trigger: Webhooks by Zapier, Catch Raw Hook. Zarejestruj otrzymany adres URL w DueReason.
  2. Krok Code by Zapier (Node.js): odczytaj nagłówek DueReason-Signature i surową treść z inputData, policz HMAC i porównaj z v1; zwróć błąd (albo ustaw flagę sprawdzaną w kolejnym kroku), gdy się nie zgadza, zamiast pozwolić Zapowi iść dalej.
  3. Krok Paths rozgałęziający na sparsowanym polu type (sparsuj surową treść do JSON-a w kroku Code, dopiero gdy podpis się zgadza, i przekaż sparsowany obiekt dalej).
  4. Na ścieżce approved krok Webhooks by Zapier: Custom Request (GET) do /approvals/{requestId} z kluczem API w nagłówku Authorization, żeby odczytać grant.
  5. Po wykonaniu akcji drugi Custom Request (POST) do /approvals/{requestId}/executions zgłaszający wynik.

Zbuduj to w Make

Moduł Webhooks > Custom webhook w Make potrzebuje włączonego ustawienia zaawansowanego dla nagłówków żądania, żeby w ogóle zobaczyć DueReason-Signature, a jego sparsowany wynik nie musi być identyczny bajt w bajt z tym, co wysłał DueReason — ta sama pułapka co zwykły Catch Hook w Zapierze. Make ma wbudowaną funkcję tekstową sha256(), ale nie ma funkcji HMAC z kluczem, więc weryfikacja podpisu wewnątrz samego Make wymaga dodatkowego kroku: albo krótkiej funkcji we własnej aplikacji Make (jeśli Twój plan obejmuje narzędzia code), albo małego przekaźnika przed Make — jednofunkcyjnego endpointu serverless, który sprawdza podpis i przekazuje do webhooka Make tylko zweryfikowane wysyłki. Nie pomijaj tego kroku dlatego, że Make akurat sparsował JSON za Ciebie; niezweryfikowany webhook to anonimowy endpoint HTTP, na który może wysyłać dane każdy, kto znajdzie jego adres.

  1. Trigger: Webhooks > Custom webhook, z włączonym "Get request headers".
  2. Zweryfikuj podpis (przekaźnikiem albo krokiem code), zanim uruchomi się kolejny moduł scenariusza.
  3. Router z dwiema trasami, filtrowanymi po {{1.body.type}} równym approval.approved albo approval.executed.
  4. Na trasie approved moduł HTTP > Make a request, GET /approvals/{{1.body.data.requestId}} z Twoim kluczem API, żeby odczytać grant.
  5. Po wykonaniu akcji kolejny moduł HTTP, POST /approvals/{{requestId}}/executions z wynikiem.

Gotowy przykład: odbierz dostęp w Okta albo Google Workspace

Połącz to z szablonem DueReason access-or-account-action, służącym do ograniczania, zawieszania lub odbierania konta bądź dostępu systemowego: jego dane wniosku niosą już subjectRef (osobę lub konto) i measure (restrict, suspend albo revoke), więc GET /approvals/{id} daje Twojemu przepływowi konkretny cel do działania, a nie samą decyzję.

  1. Na gałęzi approved, zaraz po odczytaniu grantu przez GET /approvals/{id} jak wyżej, odczytaj też action i payload z tej samej odpowiedzi: filtruj po action równym access.action, żeby ta gałąź uruchamiała się tylko dla wniosków o dostęp, a potem odczytaj payload.subjectRef i payload.measure.
  2. Zmapuj measure na wbudowaną akcję aplikacji Zapier, Make albo n8n: revoke lub suspend na akcję Deactivate User w Okcie, albo Suspend User w Google Workspace Admin, kluczowaną subjectRef jako e-mailem albo identyfikatorem użytkownika w Okcie/Google; restrict na węższą akcję, jaką udostępnia Twój dostawca tożsamości, na przykład odebranie konkretnych przypisań aplikacji albo grup zamiast dezaktywacji całego konta.
  3. Zgłoś wynik dokładnie tak, jak w każdym przepisie powyżej: POST /approvals/{id}/executions z odczytanym grantem, outcome: "succeeded" albo "failed", i detail nazywającym akcję, jaka się wykonała, na przykład "Okta: użytkownik dezaktywowany". Nieudane wywołanie Okty albo Google Workspace powinno zgłosić outcome: "failed", a nie po cichu się zatrzymać, żeby ślad audytowy i ewentualna logika ponawiania obie to zobaczyły.

DueReason nigdy samo nie wywołuje Okty ani Google Workspace: mówi Twojemu przepływowi, że człowiek zatwierdził działanie, i daje mu grant, który to udowodni, gdy zgłosi wynik. To ta sama czteroetapowa pętla co w każdym przepisie powyżej — webhook, odczyt grantu, działanie, zgłoszenie — zmienia się tylko akcja pośrodku.

Gotowy przykład: wyślij umowę do podpisu przez DocuSign albo PandaDoc

To łączy się z szablonem contract-signoff: jego dane niosą counterparty, title i draftUrl (a opcjonalnie value, które powyżej progu kieruje umowę też do działu prawnego), więc zatwierdzony wniosek od razu wskazuje Twojemu przepływowi dokument i adresata.

  1. Na gałęzi approved filtruj po action równym contract.signoff, a potem odczytaj payload.draftUrl, payload.counterparty i payload.title z tej samej odpowiedzi GET /approvals/{id}, której użyłeś do pobrania grantu.
  2. Użyj wbudowanej akcji aplikacji DocuSign albo PandaDoc w Zapierze albo Make, żeby utworzyć kopertę (envelope) z draftUrl, zaadresowaną do kontrahenta; ustaw nazwę koperty albo dokumentu na podstawie title, żeby podpisujący i Twoje własne rekordy zgadzały się co do tego, co zostało zatwierdzone.
  3. Zgłoś wynik tak samo: gdy koperta zostanie wysłana (albo, dla ściślejszego śladu audytowego, gdy wróci podpisana — zarówno DocuSign, jak i PandaDoc mają własne zdarzenia, na które może poczekać Twój przepływ), wywołaj POST /approvals/{id}/executions z grantem, outcome: "succeeded" albo "failed", i detail w rodzaju "Koperta DocuSign wysłana do legal@acme.com".

Nic tu nie zastępuje własnego kroku zatwierdzenia DueReason: umowę nadal zatwierdza lider konta (a powyżej progu wartości także dział prawny), zanim jakakolwiek koperta wyjdzie. Podpis elektroniczny automatyzuje tylko to, co dzieje się po tej decyzji — tak samo jak przykład z Okta/Google Workspace powyżej automatyzuje to, co dzieje się po decyzji o dostępie.

Gotowy przykład: utwórz fakturę kosztową w Xero albo QuickBooks

To łączy się z szablonem agent-payment: jego dane niosą amount, currency, payee, iban, purpose i opcjonalnie invoiceUrl (kierowane do działu finansów powyżej 100, a powyżej 5000 także do zarządu), więc zatwierdzona płatność od razu ma wszystko, czego potrzebuje faktura kosztowa, zanim jakiekolwiek pieniądze się przemieszczą.

  1. Na gałęzi approved, zaraz po odczytaniu grantu przez GET /approvals/{id} jak wyżej, odczytaj też action i payload z tej samej odpowiedzi: filtruj po action równym payment, żeby ta gałąź uruchamiała się tylko dla wniosków o płatność, a potem odczytaj payload.amount, payload.currency, payload.payee, payload.iban, payload.purpose i payload.invoiceUrl.
  2. Zmapuj te pola na akcję Create Bill dla Xero w Zapierze, albo akcję Create Bill (Item Based) lub Create Bill (Account Based) dla QuickBooks Online; w Make obie aplikacje mają moduł Create a Bill. W obu przypadkach: payee staje się kontrahentem albo dostawcą na fakturze (dopasowanym albo utworzonym po nazwie), amount i currency ustawiają kwotę pozycji, a purpose i invoiceUrl trafiają do pola referencji albo notatki faktury, więc zapis księgowy nadal wskazuje oryginalną fakturę.
  3. Zgłoś wynik dokładnie tak, jak w każdym przepisie powyżej: gdy Xero albo QuickBooks potwierdzi fakturę, wywołaj POST /approvals/{id}/executions z odczytanym grantem, outcome: "succeeded" albo "failed", i detail nazywającym utworzony rekord, na przykład "Xero: faktura utworzona dla Acme Ltd". Zdarzenie approval.executed niesie ten sam grant razem z payload.invoiceUrl z oryginalnego wniosku, więc uzgodnienie faktury z wnioskiem, dla którego ją zatwierdzono, nie wymaga osobnego wyszukiwania.

DueReason nigdy samo nie wywołuje Xero ani QuickBooks: najpierw dział finansów (a powyżej progu także zarząd) zatwierdza płatność, a Twój przepływ tworzy zapis księgowy dopiero, gdy ta decyzja istnieje, z grantem, który to udowodni, gdy zgłosi wynik. Ta sama czteroetapowa pętla co powyżej — webhook, odczyt grantu, działanie, zgłoszenie — zmienia się tylko docelowa aplikacja.

Zamknij pętlę

Grant jest jednorazowy: DueReason przyjmuje pierwsze zgłoszenie wykonania i odpowiada already_executed na drugie dla tego samego wniosku, więc ponowienia w Twoim narzędziu bez kodu są bezpieczne do wysłania jeszcze raz, ale nie wykonają akcji podwójnie. Traktuj already_executed jako sukces, nie błąd, gdy własna logika ponawiania w przepływie wysyła zgłoszenie jeszcze raz. A skoro sam grant dowodzi, że akcja została zatwierdzona, traktuj go tak, jak klucz API w logach przepływu: usuwaj go wszędzie tam, gdzie Twoja platforma automatyzacji przechowuje historię kroków dłużej niż trwa ważność grantu, i nigdy nie wklejaj go do współdzielonego workspace'u.

Pytania

Czy approval.approved daje mi grant, którym mogę od razu zadziałać?
Nie. Mówi, że zapadła decyzja, i zawiera id grantu, nie sam podpisany grant. Zaraz po webhooku wywołaj GET /approvals/{id}, żeby odczytać pole grant, i dopiero nim zadziałaj.
Weryfikacja HMAC zawodzi w Zapierze albo Make, mimo że sekret jest poprawny. Dlaczego?
Trigger najpewniej na nowo zserializował treść, zanim uruchomiła się Twoja weryfikacja. Zwykły Catch Hook w Zapierze i domyślny Custom webhook w Make parsują JSON, co może zmienić kolejność kluczy albo białe znaki; przełącz się na Catch Raw Hook w Zapierze albo zweryfikuj przez przekaźnik przed Make, żeby do weryfikacji HMAC dotarły dokładnie te bajty, które wysłał DueReason.
Czy mogę pominąć weryfikację podpisu dla wewnętrznego, mało istotnego przepływu?
Nie. Niezweryfikowany adres webhooka to publiczny endpoint HTTP; ktokolwiek go znajdzie, odgadnie albo powtórzy starą wysyłkę, może uruchomić Twój przepływ. Weryfikacja to cztery linijki w dowolnym języku i ten sam schemat w każdym przepisie powyżej.
Co się stanie, gdy wywołanie zgłaszające wykonanie z mojego narzędzia zawiedzie albo się powtórzy?
POST /approvals/{id}/executions przyjmuje pierwsze zgłoszenie dla danego grantu i odpowiada already_executed na każde kolejne. Zbuduj przepływ tak, by traktował already_executed jako udany wynik, a nie błąd, żeby ponowiony krok nie wywalił całego przebiegu.
Jakiego scope'u API to wymaga?
approval:read obejmuje odczyt wniosku o zatwierdzenie (i jego grantu) oraz weryfikację grantu; zgłoszenie wykonania wymaga approval:request, tego samego scope'u do zapisu co tworzenie i anulowanie wniosków — nadaj kluczowi oba, nawet jeśli Twój przepływ nigdy sam nie składa nowych wniosków.
Czy tym sposobem mogę odebrać dostęp w Okta albo Google Workspace, czy potrzebuję osobnej integracji?
Żadnej osobnej integracji: połącz ten przepis z szablonem DueReason access-or-account-action, odczytaj subjectRef i measure z danych zatwierdzonego wniosku i wywołaj nimi wbudowaną akcję Okty albo Google Workspace w Zapierze, Make albo n8n, kluczowaną przez subjectRef. Zobacz gotowy przykład powyżej.
Czy ten przewodnik pokazuje też wysyłanie umowy do podpisu elektronicznego?
Tak, przez DocuSign albo PandaDoc: połącz ten przepis z szablonem contract-signoff, odczytaj draftUrl, counterparty i title z zatwierdzonego wniosku i użyj wbudowanej akcji DocuSign albo PandaDoc w Zapierze albo Make, żeby utworzyć kopertę. Zobacz gotowy przykład powyżej.
Czy tym sposobem mogę utworzyć fakturę kosztową w Xero albo QuickBooks po zatwierdzeniu płatności?
Tak: połącz ten przepis z szablonem agent-payment, odczytaj amount, currency, payee, iban, purpose i invoiceUrl z danych zatwierdzonego wniosku i zmapuj je na akcję Create Bill w Xero albo Create Bill (Item Based)/(Account Based) w QuickBooks Online w Zapierze, albo moduł Create a Bill w Make dla którejkolwiek z tych aplikacji. Zobacz gotowy przykład powyżej.

Przeczytaj pełną dokumentację webhooków i grantów

Dokładne pola każdego zdarzenia, format nagłówka podpisu i przykład weryfikacji w Node.js, na którym oparty jest ten przepis, znajdziesz w dokumentacji API.

Przeczytaj dokumentację API

Źródła

Poradnik wyjaśnia przepisy tak, jak je rozumiemy; nie jest poradą prawną. Sprawdź tekst urzędowy i prawo krajowe, które może dodać obowiązki.

Zacznij z DueReason

Załóż bezpłatne konto, wypróbuj na żywo albo porozmawiaj z nami o swoim procesie.

Otrzymuj nowości o produkcie