Webhooki
Webhooki pozwalają SIP Caller powiadamiać Twoje systemy w czasie rzeczywistym, gdy coś wydarzy się na Twoim koncie, na przykład gdy kampania zostanie aktywowana lub zakończy się połączenie. Zamiast odpytywać REST API o zmiany, Twoja aplikacja udostępnia endpoint HTTPS, a SIP Caller wysyła do niego żądanie HTTP POST z ładunkiem JSON za każdym razem, gdy wystąpi subskrybowane zdarzenie.
Aby zacząć otrzymywać webhooki, utwórz webhook w Konsoli Webowej, wybierz zdarzenia, które Cię interesują, i przypisz go do swoich kampanii. Instrukcję krok po kroku znajdziesz na stronie Webhooki.
Ładunek zdarzenia
Każde żądanie webhooka ma treść JSON z tą samą kopertą, w której pole data zawiera szczegóły zdarzenia:
{
"id": "01928321-9129-7f25-8ad3-80c57b16d3ed",
"object": "event",
"apiVersion": 2,
"createdAt": "2024-10-12T23:47:48.133",
"type": "CampaignActivated",
"data": {
...
}
}| Pole | Opis |
|---|---|
id | Unikalny identyfikator zdarzenia. Jeśli to samo zdarzenie zostanie dostarczone więcej niż raz (na przykład po ponownej próbie), zachowuje ten sam id, więc możesz go użyć do odrzucania duplikatów. |
object | Zawsze event. |
apiVersion | Wersja formatu ładunku, zgodnie z konfiguracją webhooka. |
createdAt | Data i godzina wystąpienia zdarzenia. |
type | Typ zdarzenia, na przykład CampaignActivated lub CallEnded. |
data | Szczegóły zdarzenia. Ich zawartość zależy od typu zdarzenia, zgodnie z opisem na stronie każdego zdarzenia. |
Wersje
Każdy webhook jest skonfigurowany z wersją ładunku. Gdy SIP Caller wprowadza w ładunkach zmiany niezgodne wstecz, wydaje je w nowej wersji, dzięki czemu istniejące integracje nadal otrzymują oczekiwany format. W nowych integracjach zalecamy korzystanie z najnowszej wersji. Strona każdego zdarzenia zawiera selektor wersji, który pokazuje ładunek każdej wersji.
Typy zdarzeń
| Zdarzenie | Typ | Wysyłane, gdy |
|---|---|---|
| Kampania aktywowana | CampaignActivated | Kampania zostanie aktywowana. |
| Kampania wstrzymana | CampaignPaused | Aktywna kampania zostanie wstrzymana. |
| Kampania wznowiona | CampaignResumed | Wstrzymana kampania zostanie wznowiona. |
| Kampania anulowana | CampaignCanceled | Kampania zostanie anulowana. |
| Kampania zakończona | CampaignFinished | Kampania się zakończy. |
| Połączenie zakończone | CallEnded | Zakończy się połączenie wykonane przez kampanię. |
Weryfikacja podpisów
Każde żądanie webhooka zawiera nagłówek Sip-Caller-Signature, który pozwala zweryfikować, że żądanie zostało wysłane przez SIP Caller i nie zostało zmodyfikowane:
Sip-Caller-Signature: t=1728776932,v1=df9da282f3ffe9a7d855cc11589d86d33852ee0bbc1abaacab854c7f52e6efaeWartość t to znacznik czasu podpisania zdarzenia, a wartość v1 to podpis. Aby go zweryfikować:
- Połącz znacznik czasu (jako ciąg znaków), kropkę (
.) i surową treść JSON żądania, dokładnie w postaci, w jakiej została odebrana. - Oblicz HMAC przy użyciu funkcji skrótu SHA-256, używając sekretu podpisu webhooka jako klucza i połączonego ciągu jako wiadomości.
- Porównaj wynik, w postaci szesnastkowej, z wartością
v1. Przetwarzaj zdarzenie tylko wtedy, gdy obie wartości się zgadzają.
Na przykład w Python:
import hashlib
import hmac
def is_valid_signature(header: str, body: bytes, secret: str) -> bool:
parts = dict(item.split("=", 1) for item in header.split(","))
message = parts["t"].encode() + b"." + body
expected = hmac.new(secret.encode(), message, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts["v1"])Kompletne przykłady są dostępne dla Python i .NET. Sekret podpisu można zregenerować w Konsoli Webowej; gdy to zrobisz, natychmiast zaktualizuj swoją aplikację, ponieważ podpisy utworzone nowym sekretem nie przejdą walidacji ze starym.
Szybka odpowiedź
Twój endpoint powinien odpowiedzieć kodem statusu 2xx, gdy tylko otrzyma zdarzenie, a czasochłonne przetwarzanie wykonać później (na przykład w zadaniu w tle). Jeśli Twój endpoint nie odpowie na czas lub odpowie błędem, SIP Caller ponawia dostarczenie zgodnie z ustawieniami limitu czasu i ponownych prób webhooka. Ponieważ zdarzenie może zostać dostarczone więcej niż raz, zadbaj o idempotentność przetwarzania, korzystając z id zdarzenia.
