Korzystanie z webhooków w przepływach pracy HubSpot
Data ostatniej aktualizacji: lutego 21, 2024
Dostępne z każdą z następujących podpisów, z wyjątkiem miejsc, w których zaznaczono:
Operations Hub Professional, Enterprise |
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ą:
-
Przesyłanie danych kontaktów HubSpot do innego systemu, takiego jak CRM, gdy 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.
-
Wysyłanie alertów czatu z systemu zewnętrznego do firmowego strumienia czatu w celu powiadamiania pracowników o ważnych wydarzeniach.
- 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ł próby nieudanych webhooków przez maksymalnie trzy dni, począwszy od minuty po niepowodzeniu. Kolejne niepowodzenia będą ponawiane w coraz większych odstępach czasu, z maksymalną przerwą 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.
Więcej informacji na temat webhooków można znaleźć 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.
Konfiguracja elementu webhook w przepływie pracy
- Na koncie HubSpot przejdź do Automatyzacja > Przepływy pracy.
- Kliknij nazwę przepływu pracy.
- Kliknij ikonę +, aby dodać działanie.
- W lewym panelu wybierz opcję Wyślij webhook.
- Kliknij menu rozwijane Metoda, a następnie wybierz POST lub 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:
- Aby użyć podpisu żądania w nagłówku webhooka:
- Kliknij menu rozwijane Authentication type. Następnie wybierz opcję Dołącz podpis żądania w nagłówku.
- Następnie wprowadź swój HubSpot App ID. Dowiedz się, jak weryfikować podpisy żądań.
- Aby użyć podpisu żądania w nagłówku webhooka:
-
- Do uwierzytelniania można również użyć klucza API lub publicznej aplikacji utworzonej za pośrednictwem konta programisty.
Uwaga: od 30 listopada 2022 r. klucze API HubSpot są przestarzałe i nie są już obsługiwane. Nadal można używać zewnętrznych kluczy API do uwierzytelniania w przepływach pracy HubSpot.
-
-
- 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.
- 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:
-
-
-
-
- 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 wysyłasz żądanie do jednego z naszych 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 klu cza API na Nagłówek żądania.
-
-
- Jeśli konfigurujesz żądanie POST, możesz wybrać dołączenie wszystkich właściwości z rekordu CRM lub wysłanie tylko określonych właściwości:
- Aby uwzględnić wszystkie właściwości, w sekcji Dostosuj treść żąd ania wybierz opcję Uwzględnij wszystkie właściwości.
- Aby dołączyć tylko określone właściwości:
- W sekcji Customize request body wybierz opcję Choose specific properties.
- Kliknij menu rozwijane Wybierz właściwość. Następnie kliknij [obiekt] w tym przepływie pracy i wybierz właściwość.
- Aby zmienić nazwę właściwości w webhooku, edytuj pole tekstowe Property name . Spowoduje to jedynie aktualizację nazwy właściwości w żądaniu POST, nie zaktualizuje nazwy właściwości ani nazwy wewnętrznej w HubSpot.
- Aby dodać kolejną właściwość, kliknij przycisk Dodaj właściwość.
- Aby usunąć właściwość, kliknij ikonę kosza delete.
- Jeśli konfigurujesz żądanie GET, możesz użyć właściwości jako parametrów zapytania:
- W sekcji Parametry zapytania kliknij menu rozwijane Wybierz właściw ość. Następnie kliknij [object] w tym przepływie pracy i wybierz właściwość.
- Aby zmienić nazwę właściwości w parametrze zapytania, edytuj pole tekstowe Property name . Spowoduje to jedynie aktualizację nazwy właściwości w żądaniu GET, nie zaktualizuje nazwy właściwości ani nazwy wewnętrznej w HubSpot.
- Aby dodać kolejną właściwość, kliknij Dodaj parametr zapytania.
- Aby usunąć właściwość, kliknij ikonę kosza delete.
- Kliknij przycisk Zapisz.
Uwaga: aby wybrać wiele wyjść, odpowiedź powinna mieć strukturę obiektu JSON.
Dostosuj żądanie POST
Jeśli konfigurujesz żądanie POST, możesz wybrać dołączenie wszystkich właściwości z rekordu CRM lub wysłanie tylko określonych właściwości:
- Aby uwzględnić wszystkie właściwości, w sekcji Dostosuj treść żądania wybierz opcję Uwzględnij wszystkie właściwości.
- Aby uwzględnić tylko określone właściwości:
- W sekcji Treść żądania wybierz opcję Dostosuj treść żądania.
- Wprowadź Klucz i Wartość.
- Aby zmienić nazwę właściwości w webhooku, edytuj pole tekstowe Key . Spowoduje to jedynie aktualizację nazwy właściwości w żądaniu POST, nie zaktualizuje nazwy właściwości ani nazwy wewnętrznej w HubSpot.
- Aby dodać kolejną właściwość, kliknij przycisk Dodaj właściwość.
- Aby usunąć właściwość, kliknij ikonę kosza delete.
Dostosowywanie żądań GET
Jeśli konfigurujesz żądanie GET, możesz użyć właściwości jako parametrów zapytania, aby pobrać określone dane:
- W sekcji Parametry zapytania wprowadź Klucz, a następnie wybierz właściwość.
- Aby zmienić nazwę właściwości w parametrze zapytania, edytuj pole tekstowe Property name . Spowoduje to jedynie aktualizację nazwy właściwości w żądaniu GET, nie zaktualizuje nazwy właściwości ani nazwy wewnętrznej w HubSpot.
- Aby dodać kolejną właściwość, kliknij przycisk Dodaj właściwość.
- Aby usunąć właściwość, kliknij ikonę kosza delete.
- Wybierz typ uwierzytelniania z menu rozwijanego.
- 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 elementu webhook można wybrać, które pola mają być wyprowadzane do wykorzystania jako dane wejściowe w dalszej części przepływu 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.
- W panelu bocznym kliknij opcję Testuj działanie, aby rozwinąć sekcję.
- Kliknij menu rozwijane Obiekt, a następnie wybierz rekord do przetestowania.
- Kliknij przycisk Test.
- Aby sprawdzić szczegóły elementu webhook, 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.
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 Request signature w sekcji Authentication dla akcji Trigger a webhook, HubSpot wypełni webhook nagłówkiem X-HubSpot-Signature z hashem SHA-256 konkatenacji app-secret dla Twojej aplikacji, metody HTTP, URI i nieprzeanalizowanej treści. Więcej informacji na ten temat można znaleźć w dokumentacji dla deweloperów.
Aby zweryfikować, czy żądania otrzymywane pod adresem URL pochodzą z HubSpot:
- Posiadanie konta dewelopera. Jeśli go nie posiadasz, zarejestruj konto dewelopera.
- Posiadanie aplikacji. Jeśli nie masz aplikacji, naucz się ją tworzyć.
- Sprawdź wartość skrótu podpisu.
Wyzwalanie przepływów pracy z webhooków
Webhooki 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ą webhooków.
Używanie danych webhook w panelu danych
Dane z webhooka połączonego z Twoim 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 Automatyzacja > Przepływy pracy.
- Kliknij nazwę przepływu pracy.
- Kliknij ikonę + plus, aby dodać działanie.
- W lewym panelu wybierz akcję, która korzysta z panelu danych.
- W panelu danych, w sekcji Enrollment properties możesz wybrać jedną z właściwości z podłączonego webhooka.