Webhooki

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. Webhooki wymagają planu Enterprise.
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ą. Dostępne zdarzenia opisano w sekcji Typy zdarzeń.
• Skonfiguruj ustawienia zaawansowane zgodnie ze swoimi potrzebami. Podczas tworzenia webhooka mają one następujące wartości domyślne:
  • Limit czasu w sekundach: 30 sekund. Czas, przez jaki SIP Caller czeka na odpowiedź Twojego punktu końcowego.
  • Maksymalna liczba ponownych prób: 5. Maksymalna liczba prób dostarczenia każdego zdarzenia przez SIP Caller.
  • Maksymalny wiek zdarzenia w godzinach: 24 godziny. Zdarzenia oczekujące na wysłanie dłużej niż ten czas, na przykład gdy webhook jest wyłączony, są odrzucane.
  • Maksymalna liczba jednoczesnych połączeń: 8. Maksymalna liczba żądań, które SIP Caller wysyła jednocześnie do Twojego punktu końcowego.

Typy zdarzeń

Webhook może powiadamiać o następujących zdarzeniach:

• Kampania aktywowana: kampania zostaje aktywowana przez użytkownika z konsoli SIP Caller lub przez aplikację za pomocą REST API.
• Kampania wstrzymana: aktywna kampania zostaje wstrzymana.
• Kampania wznowiona: wstrzymana kampania zostaje ponownie aktywowana.
• Kampania anulowana: kampania zostaje anulowana.
• Kampania zakończona: kampania się kończy.
• Połączenie zakończone: połączenie wykonane przez kampanię kończy się, niezależnie od jego wyniku.

Zdarzenia kampanii zawierają konfigurację kampanii, a gdy zmiany dokonał użytkownik lub aplikacja, także źródło zmiany. Zdarzenie Połączenie zakończone zawiera szczegóły połączenia: wybrany numer i wartości jego zmiennych, wyniki dzwonienia i odpowiedzi, czasy trwania, wyniki interakcji z kontaktem (takie jak wejścia DTMF lub cele agenta AI), szczegóły przeniesienia oraz ostateczny rezultat połączenia, w tym informację, kiedy zostanie ponowione. Jest to zdarzenie, którego należy używać do aktualizowania własnych systemów, takich jak CRM, wynikiem każdego połączenia.

Dostarczanie i ponowne próby

Każde zdarzenie jest wysyłane jako żądanie HTTP POST na adres URL webhooka, z danymi JSON i nagłówkiem "Sip-Caller-Signature", dzięki czemu Twój punkt końcowy może zweryfikować, że żądanie zostało wysłane przez SIP Caller.

Dostarczenie kończy się powodzeniem, gdy Twój punkt końcowy odpowie kodem statusu HTTP 2xx w skonfigurowanym limicie czasu. Gdy punkt końcowy odpowie dowolnym innym kodem statusu, nie odpowie na czas lub jest nieosiągalny, dostarczenie kończy się niepowodzeniem, a SIP Caller automatycznie ponawia próbę: pierwsza ponowna próba jest wykonywana 5 minut po nieudanej próbie, druga godzinę później, trzecia 4 godziny później, a każda kolejna czeka o 4 godziny dłużej niż poprzednia, aż do osiągnięcia maksymalnej liczby ponownych prób. Po ostatniej próbie zdarzenie jest oznaczane jako nieudane.

Każda próba dostarczenia jest rejestrowana wraz z jej wynikiem, kodem odpowiedzi i czasem odpowiedzi, dzięki czemu możesz sprawdzić status każdego zdarzenia zgodnie z opisem w sekcji Rozwiązywanie problemów z webhookami.

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.