Dzięki webhookowi Beamcore automatycznie wysyła wiadomość na wybrany przez ciebie adres, gdy tylko coś się wydarzy, na przykład gdy zostanie utworzony projekt. W ten sposób twój własny system jest zawsze aktualny, a ty nie musisz ręcznie przepisywać danych. Interfejs Beamcore jest w języku niderlandzkim, dlatego nazwy przycisków i menu podajemy po niderlandzku wraz z tłumaczeniem.
Uwaga: menu Integraties (Integracje) nie jest domyślnie włączone. Jest to ustawienie na poziomie firmy, które Beamcore włącza dla ciebie na życzenie. Jeśli nie widzisz tego menu, skontaktuj się z Beamcore. Ponadto menu jest widoczne tylko dla właściciela firmy.
Tworzenie webhooka
- Przejdź do Integraties → Webhooks (Integracje → Webhooki) i utwórz nowy webhook.
- Wpisz Naam (Nazwa), po której rozpoznasz to połączenie.
- W polu URL wpisz adres, pod którym twój system odbiera wiadomości.
- W sekcji Events (Zdarzenia) zaznacz, o czym chcesz otrzymywać wiadomości. Musisz wybrać co najmniej jedno zdarzenie.
- Pozostaw włączoną opcję Actief (Aktywny) i zapisz.
Webhook, który nie jest aktywny, nie otrzymuje wiadomości. Za pomocą Bewerken (Edytuj) możesz później zmienić nazwę, adres URL i zdarzenia.
Dostępne zdarzenia
Beamcore wysyła wiadomości dla następujących zdarzeń:
- Project aangemaakt (Projekt utworzony, project.created): utworzono nowy projekt. Wiadomość zawiera id i nazwę projektu.
- Project gearchiveerd (Projekt zarchiwizowany, project.archived): projekt otrzymał status zarchiwizowany. Wiadomość zawiera id, nazwę i poprzedni status.
- Tekening geüpload (Rysunek przesłany, drawing.uploaded): do projektu dodano nowy rysunek. Wiadomość zawiera id i nazwę rysunku oraz id projektu.
- Test-bericht (Wiadomość testowa, webhook.test): wiadomość wysyłana przez przycisk Stuur test (Wyślij test).
Jak wygląda wiadomość
Beamcore wysyła każdą wiadomość jako żądanie POST z treścią w formacie JSON na twój adres URL. Treść zawsze zawiera trzy pola:
- event: nazwa zdarzenia, na przykład project.created.
- occurred_at: czas w zapisie ISO 8601.
- data: dane należące do zdarzenia.
Z każdym żądaniem Beamcore wysyła następujące nagłówki:
- Content-Type: application/json.
- X-Beamcore-Event: nazwa zdarzenia.
- X-Beamcore-Signature: podpis wiadomości.
Twój system musi odpowiedzieć kodem statusu z zakresu 200. Każda inna odpowiedź jest traktowana jako nieudana. Beamcore czeka na odpowiedź maksymalnie 30 sekund.
Weryfikacja podpisu
Każdy webhook przy utworzeniu automatycznie otrzymuje własny tajny klucz. Nagłówek X-Beamcore-Signature zawiera tekst sha256=, a po nim HMAC-SHA256 surowej treści wiadomości, obliczony przy użyciu tego klucza. Oblicz po swojej stronie tę samą wartość dla otrzymanej treści i porównaj ją z nagłówkiem. Jeśli się zgadzają, wiesz, że wiadomość pochodzi od Beamcore i nie została zmieniona po drodze.
Tajny klucz nie jest obecnie widoczny w portalu. Jeśli chcesz weryfikować podpis, skontaktuj się z Beamcore.
Wysyłanie wiadomości testowej
- Na liście kliknij Stuur test obok webhooka i potwierdź.
- Beamcore umieszcza w kolejce wiadomość testową na adres URL tego webhooka.
- Otwórz Integraties → Webhook log (Integracje → Log webhooków), aby sprawdzić, czy wiadomość dotarła.
Nie musisz w tym celu zaznaczać zdarzenia Test-bericht. Jeśli otrzymasz komunikat, że nic nie zostało umieszczone w kolejce, sprawdź, czy webhook jest aktywny.
Nieudane wiadomości
Jeśli dostarczenie się nie powiedzie, Beamcore próbuje ponownie, maksymalnie pięć razy dla każdej wiadomości. Między próbami czas oczekiwania rośnie: 10 sekund, 30 sekund, 2 minuty i 10 minut. Na liście webhooków przy każdym webhooku widzisz Laatste succes (Ostatni sukces) i Laatste fout (Ostatni błąd).
Log webhooków
W Integraties → Webhook log znajdziesz każdą próbę dostarczenia, od najnowszej na górze. Dla każdej próby widzisz:
- Webhook i Event (Zdarzenie): którego połączenia i którego zdarzenia dotyczy.
- Status: kod statusu zwrócony przez twój system.
- Ok?: czy dostarczenie się powiodło.
- Poging (Próba): która to była próba.
- Duur (ms) (Czas trwania w ms): ile czasu zajęła odpowiedź twojego systemu.
- Fout (Błąd): przyczyna niepowodzenia, na przykład kod statusu lub przekroczenie limitu czasu.
- Tijdstip (Czas): kiedy odbyła się próba.
Kafelki nad tabelą pokazują łączną liczbę prób oraz ile z nich zakończyło się powodzeniem, a ile niepowodzeniem w ciągu ostatnich 24 godzin.