Wykorzystanie webhooków z przepływami pracy w HubSpot

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

• Umieszczanie danych kontaktów HubSpot w innym systemie, takim jak CRM, gdy ten kontakt wypełni określony formularz w Twojej witrynie.

• Wysyłanie danych transakcji do zewnętrznego systemu obsługi przesyłek w celu utworzenia zlecenia zakupu.

• Wysyłanie alertów czatu z zewnętrznego systemu do firmowego strumienia czatu, aby powiadomić pracowników, że coś ważnego się wydarzyło.

• Pobieranie danych z innego systemu w celu aktualizacji zapisów 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 przepływu pracy. Ma to na celu usprawnienie przepływu i wydajności webhooków. Jeśli webhook działa wolno lub kończy się czasowo, wykonanie akcji przepływu może trwać dłużej niż oczekiwano.

Uwaga: HubSpot będzie ponawiał próby nieudanych webhooków przez maksymalnie trzy dni, zaczynając od jednej minuty po niepowodzeniu. Kolejne niepowodzenia będą próbowane w coraz większych odstępach czasu, przy czym maksymalna przerwa między próbami może wynosić osiem godzin. Dowiedz się o konkretnych wyjątkach kodu błędu w dokumentacji dla programistów firmy HubSpot.

Dowiedz się więcej o webhookach w dokumentacji webhooków dla programistów. Jeśli masz pytania dotyczące konkretnej implementacji webhooków z HubSpot, sięgnij po nie na forach programistów HubSpot.

Skonfiguruj webhook w swoim przepływie pracy

• W koncie HubSpot przejdź do Automatyzacja > Przepływy pracy.
• Kliknij nazwę przepływu pracy.
• Kliknij ikonę +, aby dodać działanie.
• W prawym panelu wybierz opcję Wyślij webhook.
• Kliknij menu rozwijane Method, a następnie wybierz POST lub GET.
• Wprowadź adres URL webhook. Adresy URL Webhook są ograniczone do bezpiecznego protokołu i muszą zaczynać się od HTTPS. Aby zażądać konkretnych informacji, możesz dodać parametry zapytania, takie jak ?queryparameter=abc do adresu URL Webhook. Jeśli nie zostaną dodane żadne parametry zapytania, zostanie wysłane ogólne żądanie POST lub GET.
• Skonfiguruj swój typ uwierzytelniania, aby uwierzytelnić żądania do swojego webhooka:
  • Aby użyć podpisu żądania w nagłówku twojego webhooka:
    • Kliknij menu rozwijane Typ uwierzytelniania. Następnie wybierz opcję Dołącz podpis żądania w nagłówku.
    • Następnie wprowadź swój identyfikator HubSpot App ID. Dowiedz się, jak zweryfikować podpisy żądań.

• • Możesz również użyć klucza API lub publicznej aplikacji utworzonej za pośrednictwem konta deweloperskiego do uwierzytelniania.

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.

• • • Podczas używania klucza API do uwierzytelniania, nazwa klucza API i lokalizacja klucza API są zależne od tego, jak skonfigurowany jest webhook. 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ę swojego 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 kierujesz zapytanie do jednego z naszych interfejsów API HubSpot:
      • Kliknij menu rozwijane Klucz API i wybierz sekret. Wartość sekretu musi być w formacie Bearer [YOUR_TOKEN].
      • Ustaw wartość nazwy klucza API na Authorization.
      • Ustaw wartość lokalizacji klucza API na Nagłówek żądania.
• Jeśli ustawiasz żądanie POST, możesz wybrać, aby dołączyć wszystkie właściwości z rekordu CRM lub wysłać tylko określone właściwości:
  • Aby uwzględnić wszystkie właściwości, w sekcji Dostosuj ciało żądania 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 Nazwa właściwości. Spowoduje to tylko 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 ustawiasz żądanie GET, możesz użyć właściwości jako parametrów zapytania:
  
  • W sekcji Parametry zapytania 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 parametrze zapytania, należy edytować pole tekstowe Nazwa właściwości. Spowoduje to tylko 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 parametr zapytania.
  • Aby usunąć właściwość, kliknij ikonę kosza delete.
• Kliknij przycisk Zapisz.
  
  

Uwaga: aby wybrać wiele wyjść, odpowiedź powinna być skonstruowana jako obiekt JSON.

Dostosuj swoje żądanie POST

Jeśli ustawiasz żądanie POST, możesz wybrać, aby dołączyć wszystkie właściwości z rekordu CRM lub wysłać tylko określone właściwości:

• Aby uwzględnić wszystkie właściwości, w sekcji Customize request body wybierz opcję Include all properties.
• Aby uwzględnić tylko określone właściwości:
  
  • W sekcji Ciało żąd ania wybierz opcję Dostosuj ciało żądania.
  • Wprowadź Klucz i Wartość.
  • Aby zmienić nazwę właściwości w webhooku, edytuj pole tekstowe Key . Spowoduje to tylko 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.
    
    

Dostosuj swoje żądania GET

Jeśli ustawiasz żą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 tylko aktualizację nazwy właściwości w żądaniu GET, nie zaktualizuje nazwy właściwości lub 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 zobaczyć odpowiedź webhooka. Podczas testu, gdy dane są wysyłane do 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 żądaniach testowych.

Po przetestowaniu swojego webhooka, możesz wybrać pola, które mają być wyprowadzone do użycia jako dane wejściowe w dalszej części przepływu pracy. Wybierz tylko wyjścia dostępne w każdej odpowiedzi. Jeśli wyjście jest używane w późniejszej akcji, ale nie jest dostępne w odpowiedzi, akcja nie powiedzie się.

• W panelu bocznym kliknij Testuj działanie, aby rozwinąć sekcję.
• Kliknij menu rozwijane Obiekt, a następnie wybierz Rekord do przetestowania.
• Kliknij Test.
• Aby sprawdzić szczegóły webhooka, wybierz zakładkę Odpowiedź lub Żądanie. Na każdej zakładce możesz kliknąć Otwórz wszystko, aby rozwinąć wszystkie sekcje lub Zwiń wszystko, aby zwinąć wszystkie sekcje.
  
  • W zakładce Odpowiedź, kliknij headers: lub body: aby rozwinąć każdą sekcję.
  • W zakładce Żądanie , 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 atrapą adresu URL webhook:

• W przeglądarce przejdź do strony https://webhook.site i skopiuj unikalny adres URL.
• W polu Webhook URL w swojej akcji webhook wklej adres URL.

• Po włączeniu przepływu pracy można ręcznie zapisać kontakt testowy.

Jeśli zostanie uruchomiona akcja webhook z żądaniem POST, ciało odpowiedzi JSON zostanie wysłane do webhooka zawierającego wszystkie informacje o kontakcie, w tym przesłane formularze, członkostwo w liście i wszystkie wartości właściwości kontaktu. System odbiorczy może następnie przetworzyć dane JSON i wykorzystać je we własnej aplikacji.

Jeśli zostanie wywołana akcja webhook z żądaniem GET, zostanie wysłane 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 opartych na kontaktach. Webhooks używane we wszystkich innych typach przepływów będą zwracały tylko najbardziej aktualną wartość.

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

Jeśli wybrałeś Podpisywanie żądania w sekcji Uwierzytelnianie dla akcji Wyzwalanie webhook, HubSpot wypełni webhook nagłówkiem X-HubSpot-Signature z haszem SHA-256 konkatenacji app-secret dla Twojej aplikacji, metody HTTP, URI i nieprzeanalizowanego ciała. Dowiedz się więcej na ten temat w dokumentacji dla deweloperów.

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

• Posiadaj konto deweloperskie. Jeśli go nie masz, załóż konto deweloperskie.
• Posiadanie aplikacji. Jeśli nie masz aplikacji, naucz się ją tworzyć.
• Sprawdź wartość hashową podpisu.