Przejdź do głównej treści
Webhooks pozwalają AgencyHandy przesyłać dane do Twoich zewnętrznych systemów w momencie zmiany — bez konieczności odpytywania. Gdy skonfigurowane zdarzenie zostanie uruchomione (na przykład zamówienie zostanie zaktualizowane lub zgłoszenie zostanie utworzone), AgencyHandy wysyła żądanie HTTP POST z ładunkiem JSON na podany przez Ciebie adres URL punktu końcowego. Ułatwia to synchronizację zewnętrznych narzędzi, takich jak systemy CRM, systemy rozliczeniowe lub niestandardowe pulpity nawigacyjne, z Twoją przestrzenią roboczą AgencyHandy w czasie rzeczywistym.
Przestrzenie robocze w planie Business Pro obsługują do 30 000 zdarzeń webhook na okres rozliczeniowy. Przed skonfigurowaniem automatyzacji o dużej częstotliwości sprawdź limity swojego planu.

​
Obsługiwane zdarzenia

Możesz subskrybować webhook do dowolnej kombinacji następujących zdarzeń:
KategoriaZdarzenia
UsługaUtworzona, zaktualizowana, usunięta
ZamówienieUtworzone, zaktualizowane, usunięte
ZadanieUtworzone, przypisane, ukończone, zaktualizowane
FakturaZmiana statusu
Klient / UżytkownikNowy klient dodany, klient/użytkownik usunięty
PropozycjaWysłana, odebrana, zaakceptowana, odrzucona
ZgłoszenieUtworzone, przypisane, zmiana statusu
PłatnośćOdebrana, nieudana
Pakiet usługUtworzony, zaktualizowany, usunięty

​
Utwórz webhook

1

Przejdź do zarządzania webhookami

Na lewym pasku bocznym przejdź do Integracje → Zarządzanie webhookami.
2

Uwierzytelnij swój token

Kliknij przycisk Zarządzanie, aby uwierzytelnić swój token webhook. Ten token służy do podpisywania wychodzących ładunków, dzięki czemu możesz zweryfikować, że pochodzą z AgencyHandy.
3

Utwórz nowy webhook

Kliknij Utwórz nowy webhook, aby otworzyć formularz konfiguracji webhooka.
4

Wprowadź adres URL punktu końcowego

W polu Adres URL punktu końcowego wprowadź adres URL zewnętrznego systemu, który powinien odbierać dane webhooks. Musi to być publicznie dostępny punkt końcowy POST.
5

Wybierz typ zawartości

Wybierz JSON jako typ zawartości. AgencyHandy wysyła wszystkie ładunki webhooks jako application/json.
6

Wybierz zdarzenia webhooks

Wybierz każde zdarzenie, które powinno wyzwolić ten webhook. Możesz wybierać zdarzenia z wielu kategorii — na przykład Zamówienie: Utworzone i Faktura: Zmiana statusu mogą wskazywać na ten sam punkt końcowy.
7

Aktywuj webhook

Włącz przycisk radiowy Aktywny. Gdy jest aktywny, AgencyHandy dostarcza ładunki dla wszystkich wybranych zdarzeń do Twojego punktu końcowego w czasie rzeczywistym.
8

Zapisz konfigurację

Sprawdź ustawienia, a następnie kliknij Zapisz. Webhook pojawia się na liście i natychmiast zaczyna dostarczać zdarzenia.

​
Przetestuj webhook

Po utworzeniu webhooka wyślij testowy ładunek, aby potwierdzić, że Twój punkt końcowy jest dostępny i poprawnie przetwarza dane.
1

Otwórz webhook

Na liście zarządzania webhookami kliknij webhook, który chcesz przetestować.
2

Kliknij Testuj zdarzenie

Kliknij przycisk Testuj zdarzenie na stronie szczegółów webhooka.
3

Wybierz zdarzenie testowe

Wybierz przykładowe zdarzenie z listy zdarzeń skonfigurowanych dla tego webhooka (np. Zamówienie: Utworzone).
4

Wyślij testowy ładunek

Kliknij Wyślij. AgencyHandy opublikuje przykładowy ładunek na Twoim adresie URL punktu końcowego.
5

Zweryfikuj wynik

Sprawdź swój zewnętrzny system, aby potwierdzić, że testowy ładunek dotarł i został przetworzony zgodnie z oczekiwaniami. W AgencyHandy kliknij webhook, aby przejrzeć jego historię — możesz zobaczyć pełne żądanie, odpowiedź zwróconą przez Twój punkt końcowy i ponownie dostarczyć dowolne poprzednie zdarzenie, jeśli zajdzie taka potrzeba.
Użyj narzędzia takiego jak Webhook.site lub RequestBin jako tymczasowego punktu końcowego podczas konfiguracji, aby sprawdzić dokładny kształt ładunku przed podłączeniem rzeczywistego systemu.

​
Uwierzytelniaj ładunki webhooków

Każde wychodzące żądanie webhook z AgencyHandy zawiera nagłówek sygnatury, którego Twój punkt końcowy może użyć do weryfikacji, że ładunek jest autentyczny i nie został zmodyfikowany.

​
Nagłówek sygnatury

x-ah-sig: <signature>
AgencyHandy dodaje ten nagłówek do każdego żądania webhook. Wyodrębnij wartość z przychodzących żądań i przekaż ją do punktu końcowego weryfikacji.

​
Zweryfikuj sygnaturę webhooka

Wyślij następujące żądanie, aby potwierdzić autentyczność ładunku: 
POST https://api.agencyhandy.com/api/v1/webhooks/verify-signature
Content-Type: application/json
​
webhookId
string
wymagane
Identyfikator webhooka, który otrzymał zdarzenie. Znajdziesz go na stronie szczegółów webhooka w AgencyHandy.
​
signature
string
wymagane
Wartość nagłówka x-ah-sig z przychodzącego żądania webhooka.
​
secret
string
wymagane
Sekret webhooka widoczny na stronie szczegółów webhooka w AgencyHandy.
​
payload
object
wymagane
Surowe ciało JSON odebrane z żądania webhooka AgencyHandy.
const url = 'https://api.agencyhandy.com/api/v1/webhooks/verify-signature';

const postData = {
  webhookId: 'your_webhook_id',
  signature: 'your_signature',   // value of x-ah-sig header
  secret: 'your_webhook_secret',
  payload: {},                   // the parsed JSON body from AgencyHandy
};

const response = await fetch(url, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(postData),
});

const data = await response.json();
console.log(data); // { "verification_status": "SUCCESS" }
Odpowiedzi
​
verification_status
string
SUCCESS gdy sygnatura jest prawidłowa. FAILED gdy weryfikacja nie powiedzie się (HTTP 403).
Success (200)
{
  "verification_status": "SUCCESS"
}
Failure (403)
{
  "type": "PermissionError",
  "status": 403,
  "verification_status": "FAILED"
}
Zachowaj poufność swojego sekretu webhooka. Regularnie go rotuj i natychmiast aktualizuj logikę weryfikacji po rotacji. Nigdy nie ujawniaj go w kodzie po stronie klienta ani w publicznych repozytoriach.

​
Ważne uwagi

  • Adres URL Twojego punktu końcowego musi być publicznie dostępnym adresem URL HTTPS POST.
  • Jeśli Twój punkt końcowy jest tymczasowo niedostępny, sprawdź panel historii webhooka w AgencyHandy — możesz ponownie dostarczyć dowolne poprzednie zdarzenie bezpośrednio stamtąd.
  • Regularnie monitoruj aktywność webhooków, aby wykrywać nieudane dostarczenia lub nieautoryzowane próby dostępu.
  • Webhooks, które wielokrotnie kończą się niepowodzeniem, mogą zostać wstrzymane przez AgencyHandy — przeglądaj dzienniki dostaw, aby wcześnie wykrywać problemy.