Korzystanie z webhooków w przepływach pracy HubSpot

Użyj webhooków w przepływach pracy, aby wysyłać lub pobierać informacje między HubSpot i innymi narzędziami zewnętrznymi. Istnieje wiele różnych zastosowań webhooków, przykłady popularnych przypadków użycia webhooków obejmują:

• Wysyłanie danych kontaktowych HubSpot do innego systemu, takiego jak CRM, gdy ten kontakt wypełni określony formularz na Twojej stronie.

• Wysyłanie danych transakcji do zewnętrznego systemu obsługi wysyłek w celu utworzenia zamówienia zakupu.

• Pobieranie danych z innego systemu w celu aktualizacji rekordów HubSpot.

Za pomocą przepływów pracy można wysyłać zarówno żądania POST, jak i GET. HubSpot reguluje ruch webhooków oddzielnie od innych procesów workflow. Ma to na celu usprawnienie przepływu pracy i wydajności webhooków. Gdy webhook jest powolny lub przekroczy limit czasu, wykonanie akcji przepływu pracy może potrwać dłużej niż oczekiwano.

Uwaga: HubSpot będzie ponawiał nieudane webhooki przez maksymalnie trzy dni, począwszy od minuty po niepowodzeniu. Kolejne niepowodzenia będą ponawiane w coraz większych odstępach czasu, z maksymalnym odstępem ośmiu godzin między próbami. Przepływy pracy nie będą ponawiane po otrzymaniu kodów stanu odpowiedzi serii 4XX.
Wyjątkiem od tej reguły są błędy limitu szybkości 429; przepływy pracy będą automatycznie ponawiać próbę po otrzymaniu odpowiedzi 429 i będą przestrzegać nagłówka Retry-After, jeśli jest obecny. Retry-After jest rejestrowany w milisekundach. Więcej informacji na temat określonych wyjątków kodów błędów można znaleźć w dokumentacji deweloperskiej HubSpot.

Dowiedz się więcej o webhookach w dokumentacji webhooków dla deweloperów. Jeśli masz pytania dotyczące konkretnej implementacji webhooków w HubSpot, skontaktuj się z HubSpot Developers Forums.

Konfigurowanie żądania POST

• Na koncie HubSpot przejdź do sekcji Automatyzacje > Przepływy pracy.
• Aby edytować istniejący przepływ pracy, kliknij jego nazwę. Możesz też utworzyć nowy przepływ pracy.
• W edytorze przepływu pracy kliknij ikonę + plus, aby dodać akcję.
• W lewym panelu, w sekcji Operacje na danych, wybierz opcję Wyślij webhook.
  

• Kliknij menu rozwijane Metoda i wybierz opcję POST.
• Wprowadź adres URL elementu webhook.
  • Adresy URL elementów webhook są ograniczone do bezpiecznego protokołu i muszą zaczynać się od HTTPS.
  • Aby zażądać określonych informacji, można dodać do adresu URL elementu webhook parametry zapytania, takie jak ?queryparameter=abc .
  • Jeśli nie dodano żadnych parametrów zapytania, zostanie wysłane ogólne żądanie POST lub GET.
• Skonfiguruj typ uwierzytelniania, aby uwierzytelniać żądania do elementu webhook. Możesz użyć podpisu żądania w nagłówku webhooka lub użyć klucza API:
  • Aby użyć podpisu żądania w nagłówku elementu webhook:
    • Kliknij menu rozwijane Authentication type. Następnie wybierz opcję Include request signature in header.
    • Następnie wprowadź swój HubSpot App ID. Dowiedz się, jak weryfikować podpisy żądań.

• • Aby użyć klucza API lub aplikacji publicznej utworzonej za pośrednictwem konta programisty do uwierzytelniania:

• • • W przypadku używania klucza API do uwierzytelniania nazwa klucza API i lokalizacja klucza API zależą od sposobu skonfigurowania webhooka. Ze względów bezpieczeństwa klucz API nie będzie wyświetlany w żadnych żądaniach testowych. Aby użyć klucza API:
      • Kliknij menu rozwijane Typ uwierzytelniania. Następnie wybierz Klucz API.

• • • • Wprowadź nazwę klucza API.
      • Kliknij menu rozwijane Lokalizacja klucza API. Następnie wybierz Parametry zapytania lub Nagłówek żądania. Dowiedz się więcej o używaniu kluczy API w HubSpot.
    • Jeśli składasz zapytanie do interfejsu API HubSpot:
      • Kliknij menu rozwijane Klucz API i wybierz wartość tajną. Wartość tajna musi być w formacie Bearer [YOUR_TOKEN].
      • Ustaw wartość nazwy klucza API na Authorization.
      • Ustaw wartość lokalizacji klu cza API na Nagłówek żądania.

• Aby uwzględnić wszystkie właściwości, wybierz opcję Include all [object] properties.
• Aby uwzględnić tylko określone właściwości:
  
  • Wybierz opcję Customize request body.
  • Aby dostosować treść żądania przy użyciu właściwości HubSpot, wprowadź Key i wybierz właściwość. Aby dodać inną właściwość, kliknij Dodaj właściwość.
  • Aby dostosować treść żądania za pomocą pola statycznego, wprowadź Klucz i Wartość. Aby dodać inną właściwość, kliknij Dodaj wartość statyczną.

• • Aby usunąć właściwość lub wartość statyczną, kliknij ikonę kosza delete.
• Kliknij przycisk Zapisz.

Uwaga: aby wybrać wiele wyjść, odpowiedź powinna mieć strukturę obiektu JSON.

Konfiguracja żądania GET

• Na koncie HubSpot przejdź do sekcji Automatyzacje > Przepływy pracy.
• Aby edytować istniejący przepływ pracy, kliknij jego nazwę. Możesz też utworzyć nowy przepływ pracy.
• W edytorze przepływu pracy kliknij ikonę + plus, aby dodać akcję.
• W lewym panelu, w sekcji Operacje na danych, wybierz opcję Wyślij webhook.
  

• Kliknij menu rozwijane Metoda i wybierz opcję GET.
• Wprowadź adres URL elementu webhook.
  • Adresy URL elementów webhook są ograniczone do bezpiecznego protokołu i muszą zaczynać się od HTTPS.
  • Aby zażądać określonych informacji, do adresu URL elementu webhook można dodać parametry zapytania, takie jak ?queryparameter=abc .
  • Jeśli nie dodano żadnych parametrów zapytania, zostanie wysłane ogólne żądanie POST lub GET.
• Skonfiguruj typ uwierzytelniania, aby uwierzytelniać żądania do elementu webhook. Możesz użyć podpisu żądania w nagłówku webhooka lub użyć klucza API:
  • Aby użyć podpisu żądania w nagłówku elementu webhook:
    • Kliknij menu rozwijane Authentication type. Następnie wybierz opcję Include request signature in header.
    • Następnie wprowadź swój HubSpot App ID. Dowiedz się, jak weryfikować podpisy żądań.

• • Aby użyć klucza API lub aplikacji publicznej utworzonej za pośrednictwem konta programisty do uwierzytelniania:

• • • W przypadku korzystania z klucza API do uwierzytelniania nazwa klucza API i lokalizacja klucza API zależą od sposobu skonfigurowania webhooka. Ze względów bezpieczeństwa klucz API nie będzie wyświetlany w żadnych żądaniach testowych. Aby użyć klucza API:
      • Kliknij menu rozwijane Typ uwierzytelniania. Następnie wybierz Klucz API.

• • • • Wprowadź nazwę klucza API.
      • Kliknij menu rozwijane Lokalizacja klucza API. Następnie wybierz Parametry zapytania lub Nagłówek żądania. Dowiedz się więcej o używaniu kluczy API w HubSpot.
    • Jeśli składasz zapytanie do interfejsu API HubSpot:
      • Kliknij menu rozwijane Klucz API i wybierz wartość tajną. Wartość tajna musi być w formacie Bearer [YOUR_TOKEN].
      • Ustaw wartość nazwy klucza API na Authorization.
      • Ustaw wartość lokalizacji klu cza API na Nagłówek żądania.

• Aby użyć właściwości HubSpot jako parametru zapytania:
  • W sekcji Query parameters wprowadź Key, a następnie wybierz właściwość.
  • Aby dodać kolejną właściwość, kliknij przycisk Dodaj właściwość.
  • Aby usunąć właściwość, kliknij ikonę kosza delete.
• Aby użyć wartości statycznej jako parametru zapytania:
  • W sekcji Query parameters wprowadź Key, a następnie wprowadź wartość.
  • Aby dodać kolejną właściwość, kliknij Dodaj wartość statyczną.
  • Aby usunąć właściwość, kliknij ikonę kosza delete.
• Kliknij przycisk Zapisz.

Przetestuj swój webhook w HubSpot

Podczas konfigurowania webhooka POST lub GET można wykonać test, aby wyświetlić odpowiedź webhooka. Podczas testu, gdy dane są wysyłane i pobierane od strony trzeciej, istniejące rekordy w HubSpot nie zostaną naruszone. Jeśli używasz klucza API do uwierzytelniania, klucz API nie będzie wyświetlany w żadnych żądaniach testowych.

Po przetestowaniu webhooka możesz wybrać, które pola mają być wyprowadzane do wykorzystania jako dane wejściowe później w przepływie pracy. Wybierz tylko dane wyjściowe dostępne w każdej odpowiedzi. Jeśli dane wyjściowe są używane w późniejszej akcji, ale nie są dostępne w odpowiedzi, akcja zakończy się niepowodzeniem.

• Na koncie HubSpot przejdź do sekcji Automatyzacje > Przepływy pracy.
• Kliknij nazwę przepływu pracy.
• W edytorze przepływu pracy kliknij akcję Wyślij webhook.
• W lewym panelu kliknij Test action, aby rozwinąć sekcję.
• Jeśli testujesz żądanie POST, kliknij menu rozwijane [object], a następnie wybierz rekord do przetestowania.
• Kliknij przycisk Test.
• Aby sprawdzić szczegóły webhooka, wybierz kartę Odpowiedź lub Żądanie. Na każdej karcie możesz kliknąć Otwórz wszystko, aby rozwinąć wszystkie sekcje, lub Zwiń wszystko, aby zwinąć wszystkie sekcje.
  
  • Na karcie Response kliknij headers: lub body: , aby rozwinąć każdą sekcję.
  • Na karcie Request kliknij httpHeaders: , aby rozwinąć sekcję.
    
    

Przetestuj swój webhook zewnętrznie

Po utworzeniu przepływu pracy z akcją webhook można przeprowadzić szybki test z fikcyjnym adresem URL webhook:

• W przeglądarce przejdź do strony https://webhook.site i skopiuj unikalny adres URL.
• W polu Webhook URL w akcji webhook wklej adres URL.
• Po włączeniu przepływu pracy można ręcznie zarejestrować kontakt testowy.
  
  

• Podczas testowania webhooka na zewnątrz:
  • Jeśli uruchomiona zostanie akcja webhook z żądaniem POST, do webhooka zostanie wysłana treść odpowiedzi JSON zawierająca wszystkie informacje o kontakcie, w tym przesłane formularze, członkostwo na liście i wszystkie wartości właściwości kontaktu. System odbierający może następnie przeanalizować dane JSON i użyć ich we własnej aplikacji.
  • Jeśli uruchomiona zostanie akcja webhook z żądaniem GET, wysłane zostanie ogólne żądanie GET, chyba że zastosowano dodatkowe parametry zapytania.

Uwaga: historyczne wartości właściwości będą zwracane tylko w przepływach pracy opartych na kontaktach. Webhooki używane we wszystkich innych typach przepływów pracy zwrócą tylko najnowszą wartość.

Weryfikacja podpisów żądań w webhookach przepływu pracy

W przypadku wybrania opcji Podpis żąd ania w sekcji Uwierzytelnianie dla akcji Wyzwól web hook, HubSpot wypełni webhook nagłówkiem X-HubSpot-Signature zawierającym skrót SHA-256 konkatenacji sekretu aplikacji, metody HTTP, URI i nieprzeanalizowanej treści. Więcej informacji na ten temat można znaleźć w dokumentacji dla deweloperów.

Aby sprawdzić, czy żądania otrzymane pod adresem URL pochodzą z HubSpot:

• Posiadaj konto dewelopera. Jeśli go nie posiadasz, załóż konto dewelopera.
• Posiadanie aplikacji. Jeśli nie masz aplikacji, dowiedz się, jak ją utworzyć.
• Sprawdźwartość skrótu podpisu.

Wyzwalanie przepływów pracy z webhooków

Webhooków można używać do wyzwalania przepływów pracy. Gdy dane zmienią się w aplikacji innej firmy, może to wyzwolić przepływ pracy. Dowiedz się więcej o wyzwalaniu przepływów pracy z webhooków.

Używanie danych webhook w panelu danych

Dane z elementu webhook połączonego z kontem mogą być wykorzystywane do określonych działań w panelu danych.

Aby użyć danych z podłączonego webhooka:

• Na koncie HubSpot przejdź do sekcji Automatyzacje > Przepływy pracy..
• Kliknij nazwę przepływu pracy.
• Kliknij ikonę + plus, aby dodać akcję.
• W lewym panelu wybierz akcję , która korzysta z panelu danych.
• W panelu danych kliknij menu rozwijane View properties or action outputs from i wybierz opcję Webhook trigger. Następnie można użyć właściwości z podłączonego webhooka.