Przegląd

SIP Caller może wywoływać webhooki, aby powiadamiać systemy zewnętrzne o zdarzeniach zachodzących na naszej platformie. W ten sposób można opracować wiele przydatnych, niestandardowych integracji między SIP Caller a innymi systemami.
Procedura obejmuje 2 kroki:

1. Utworzenie webhooka.
2. Skonfigurowanie kampanii z istniejącym webhookiem.

Tworzenie webhooka

Aby utworzyć webhooka, zaloguj się do SIP Caller i przejdź do Ustawienia > Webhooki. Następnie kliknij przycisk "Utwórz", aby otworzyć okno dialogowe tworzenia webhooka i postępuj następująco:

• Wprowadź przyjazną nazwę dla webhooka, dzięki czemu będziesz mógł łatwo go wybrać później.
• Wprowadź adres URL, który SIP Caller ma wywoływać, gdy wystąpią zdarzenia.
• Wybierz wersję. Zalecamy korzystanie z najnowszej wersji, aby wykorzystać najnowsze funkcje, ale możesz również skonfigurować starszą wersję ze względu na kompatybilność wsteczną.
• Wybierz zdarzenia, które Cię interesują.
• Skonfiguruj limit czasu, maksymalną liczbę ponownych prób, maksymalny wiek zdarzenia i maksymalną liczbę jednoczesnych połączeń, zgodnie ze swoimi potrzebami.

Konfigurowanie kampanii do wywoływania webhooków

Po utworzeniu webhooka musisz skonfigurować kampanie, aby z niego korzystały. Aby to zrobić, po prostu wybierz webhook w zakładce Integracja.

Włączanie i wyłączanie webhooków

Jeśli napotkasz problem podczas przetwarzania webhooków wywoływanych przez SIP Caller, możesz wstrzymać generowanie tych zdarzeń. Gdy to zrobisz, SIP Caller będzie kolejkować te zdarzenia przez czas skonfigurowany podczas jego tworzenia, dając Ci czas na naprawienie algorytmu przetwarzania zdarzeń, dzięki czemu będziesz mógł następnie ponownie włączyć webhooki. Aby to zrobić, przejdź do Ustawienia > Webhooki i wybierz przyciski "Włącz" lub "Wyłącz" w kolumnie Akcje.

Regenerowanie sekretu podpisu

Z kolumny Akcje na liście webhooków możesz również kliknąć przycisk, aby zregenerować sekret podpisu. Spowoduje to, że SIP Caller zacznie podpisywać webhooki przy użyciu nowego sekretu. Każda integracja korzystająca ze starego sekretu przestanie działać, ponieważ walidacja się nie powiedzie, więc musisz zachować ostrożność podczas wykonywania tej czynności.

Walidacja podpisu webhooka

Każde powiadomienie webhook wysłane przez SIP Caller będzie miało nagłówek "Sip-Caller-Signature" w żądaniu HTTP, ustawiony na wartość podobną do następującej:

t=1728776932,v1=df9da282f3ffe9a7d855cc11589d86d33852ee0bbc1abaacab854c7f52e6efae

Wartość przypisana do "t" to znacznik czasu informujący, kiedy zdarzenie zostało wygenerowane. Wartość przypisana do "v1" to podpis webhooka. Będziesz potrzebować obu wartości do weryfikacji, w następujący sposób:

1. Połącz znacznik czasu (jako ciąg znaków), kropkę (.) oraz dane JSON otrzymane w treści żądania HTTP. Na przykład:

   1728776932.{"id" : "01928322-860c-77f9-9c3b-7f8abe3b6afd".......}

2. Oblicz oczekiwany podpis webhooka, obliczając HMAC przy użyciu funkcji skrótu SHA256. Użyj sekretu podpisu webhooka jako klucza, a wartość wynikającą z połączenia w poprzednim kroku jako wiadomości.
3. Porównaj obliczony podpis webhooka z wartością pobraną z "v1" w nagłówku żądania. Jeśli obie wartości się zgadzają, możesz bezpiecznie kontynuować przetwarzanie zdarzenia webhooka.

Stworzyliśmy przykłady kodu pokazujące, jak wykonać tę walidację w aplikacji Python lub .NET.

Rozwiązywanie problemów z webhookami

W konsoli SIP Caller > Ustawienia > Webhooki możesz kliknąć webhook i sprawdzić wszystkie zdarzenia, o których wysłano powiadomienia.
Listę można filtrować, aby zidentyfikować szukane zdarzenie. Następnie, po kliknięciu zdarzenia, po prawej stronie zostanie wyświetlony panel ze szczegółami każdej próby powiadomienia.

Dane referencyjne webhooków

Webhooki generowane przez SIP Caller to żądania HTTP POST zawierające JSON jako dane, a każde żądanie jest oznaczone wersją, dzięki czemu możemy rozwijać format danych w czasie bez psucia istniejących integracji. Pełne dane referencyjne JSON dla każdego typu zdarzenia i wersji są dostępne na stronie Dane referencyjne webhooków.