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

1. Aby edytować istniejący przepływ pracy, kliknij jego nazwę. Możesz też utworzyć nowy przepływ pracy.
2. W edytorze przepływu pracy kliknij ikonę + plus, aby dodać akcję.
3. W lewym panelu, w sekcji Operacje na danych, wybierz opcję Wyślij webhook.
   

5. Kliknij menu rozwijane Metoda i wybierz opcję POST.
6. 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.
7. 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 korzystaniu z kluczy API w HubSpot.
     • Jeśli wysyłasz żądanie do interfejsów API HubSpot:
       • Kliknij menu rozwijane Klucz API i wybierz sekret. Wartość tajna musi być w formacie Bearer [YOUR_TOKEN].
       • Ustaw wartość nazwy klucza API na Authorization.
       • Ustaw wartość lokalizacji klucza API na Nagłówek żądania.
8. Aby uwzględnić wszystkie właściwości, wybierz opcję Include all [object] properties.
9. 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ć kolejną właściwość, kliknij Dodaj wartość statyczną.
   • Aby usunąć właściwość lub wartość statyczną, kliknij ikonę kosza delete.
10. Kliknij przycisk Zapisz.

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

Konfiguracja żądania GET

1. Aby edytować istniejący przepływ pracy, kliknij jego nazwę. Możesz też utworzyć nowy przepływ pracy.
2. W edytorze przepływu pracy kliknij ikonę + plus, aby dodać akcję.
3. W lewym panelu, w sekcji Operacje na danych, wybierz opcję Wyślij webhook.
   

5. Kliknij menu rozwijane Metoda i wybierz opcję GET.
6. 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.
7. 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 korzystaniu z kluczy API w HubSpot.
     • Jeśli wysyłasz żądanie do interfejsów API HubSpot:
       • Kliknij menu rozwijane Klucz API i wybierz sekret. Wartość tajna musi być w formacie Bearer [YOUR_TOKEN].
       • Ustaw wartość nazwy klucza API na Authorization.
       • Ustaw wartość lokalizacji klucza API na Nagłówek żądania.
8. Jeśli konfigurujesz żądanie GET, możesz użyć właściwości HubSpot lub dodać wartości statyczne jako parametry zapytania:

9. Aby użyć właściwości HubSpot jako parametru zapytania:
   • W sekcji Parametry zapytania wprowadź Klucz, 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ę usuwania delete.
10. 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ę usuwania delete.
11. Kliknij przycisk Zapisz.

Ustaw limit szybkości dla elementu webhook

Ustaw limit szybkości, aby określić, jak szybko powinna być wykonywana akcja webhook. Limit szybkości będzie miał również wpływ na wszystkie kolejne akcje w przepływie pracy.

1. Kliknij nazwę przepływu pracy.
2. W edytorze przepływu pracy kliknij akcję Wyślij webhook.
3. W lewym panelu kliknij opcję Konfiguruj limit szybkości, aby rozwinąć sekcję.
4. Kliknij, aby włączyć przełącznik Turn on rate limiting. Domyślnie ustawienie to jest wyłączone.
5. Skonfiguruj limit szybkości:
   • Wykonania akcji: ustaw maksymalną liczbę wykonań w danym okresie czasu.
   • Ramy czasowe: ustaw ramy czasowe dla limitu szybkości. Ramy czasowe można ustawić w sekundach, minutach lub godzinach.

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.

1. Kliknij nazwę przepływu pracy.
2. W edytorze przepływu pracy kliknij akcję Wyślij webhook.
3. W lewym panelu kliknij Test action, aby rozwinąć sekcję.
4. Jeśli testujesz żądanie POST, konfiguracja testu elementu webhook będzie się różnić w zależności od tego, czy wybrałeś opcję Customize request body, czy Include all [object] properties w akcji webhook.
   • Jeśli wybrano opcję Customize request body, należy wprowadzić wartości testowe właściwości dla testu.
   • Jeśli wybrano opcję Uwzględnij wszystkie właściwości [obiektu], kliknij menu rozwijane [obiekt], a następnie wybierz rekord do przetestowania.
5. Kliknij przycisk Test.
6. Aby sprawdzić szczegóły webhooka, wybierz kartę Response lub Request. 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:

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

4. 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

Elementy webhook mogą być używane 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 za pomocą elementów webhook.

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:

1. .
2. Kliknij nazwę przepływu pracy.
3. Kliknij ikonę + plus, aby dodać akcję.
4. W lewym panelu wybierz akcję , która korzysta z panelu danych.
5. 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.