Sign inGet Started

Adresy URL wywołań zwrotnych SMS

Adres URL wywołania zwrotnego odbiera zdarzenia jednej wiadomości SMS lub wszystkich wiadomości w profilu wiadomości zamiast Twoich punktów końcowych webhooków. Użyj go, gdy wiadomość lub program potrzebuje własnego odbiorcy.

Zarządzaj sekretem podpisywania, historią prób i ponownym odtwarzaniem w panelu albo za pomocą API i poleceń bird webhooks callbacks. Ustaw adres URL profilu podczas tworzenia profilu wiadomości lub jego aktualizacji.

Wybierz, dokąd trafiają zdarzenia

Adres URL jest ustalany raz, w momencie przyjęcia wiadomości, i pozostaje niezmienny przez cały czas jej istnienia. Późniejsza zmiana profilu nie przekierowuje wiadomości, która jest już w drodze.

WiadomośćUżywany adres URL
Wysłana z options.callback_urlTen adres URL
Wysłana z options.callback_url ustawionym na nullBrak: zdarzenia trafiają do Twoich punktów końcowych webhooków
Wysłana bez niego, w ramach profilu wiadomościoptions.callback_url profilu
Odebrana na numerze profilu wiadomościinbound.callback_url profilu, a następnie jego options.callback_url
Żaden z powyższych nie podaje adresu URLBrak: zdarzenia trafiają do Twoich punktów końcowych webhooków

URL musi używać HTTPS, mieć najwyżej 2048 znaków i wskazywać adres publiczny. Host prywatny, loopback lub link-local zwraca 422.

Lista prób wywołań zwrotnych pokazuje, dokąd dostarczono zdarzenie odebranej wiadomości.

Co zastępuje URL

Gdy obowiązuje adres URL, zdarzenia tej wiadomości omijają Twoje punkty końcowe webhooków. Inne wiadomości w obszarze roboczym nadal do nich trafiają. Nieudane wywołanie zwrotne nie jest przekierowywane do Twoich punktów końcowych: aby je odzyskać, użyj ponownego odtwarzania.

MCP Subskrypcje Events i endpointy konektorów nadal otrzymują zdarzenia wiadomości.

callback_events profilu wiadomości określają, które zdarzenia wychodzące trafiają na adres URL, spośród sms.accepted, sms.sent, sms.delivered, sms.undelivered, sms.failed, sms.rejected i sms.expired. Zdarzenie pominięte na liście nie trafia też do żadnego punktu końcowego webhooka dla tej wiadomości. Profil bez listy oraz wysyłka bez profilu dostarczają każde zdarzenie wychodzące. sms.received nigdy nie jest filtrowane. Ładunki to zdarzenia SMS.

Weryfikuj podpisy

Wywołania zwrotne korzystają z tych samych nagłówków Standard Webhooks i podpisu HMAC-SHA256 co punkty końcowe webhooków, więc Twój dotychczasowy kod weryfikacji działa bez zmian. Kluczem jest sekret podpisywania wywołań zwrotnych Twojego obszaru roboczego, jeden sekret wspólny dla wszystkich adresów URL wywołań zwrotnych i wszystkich żądań webhooków sekwencji głosowych, więc rotacja obejmuje oba te miejsca.

Pierwszy sekret nigdy nie jest wyświetlany. Wykonaj jego rotację w panelu w sekcji Webhooks → Direct callbacks lub za pomocą Rotate callback signing secret, aby otrzymać sekret, którego możesz użyć. Nowy sekret wyświetla się tylko raz, więc zapisz go przed opuszczeniem strony. Przez następne 24 godziny każde wywołanie zwrotne jest podpisywane zarówno starym, jak i nowym sekretem, więc możesz wdrożyć nowy bez utraty dostarczeń. Obszar roboczy może mieć jednocześnie najwyżej 5 ważnych sekretów, dlatego ponowna rotacja w okresie nakładania się może zostać odrzucona. Rotacja zaczyna obowiązywać w ciągu około minuty.

Wykonaj rotację, zanim zaczniesz polegać na weryfikacji: do tego czasu wywołania zwrotne mają podpis utworzony sekretem, którego nie możesz odczytać.

Ponowne próby i duplikaty

Wywołania zwrotne stosują harmonogram ponownych prób punktów końcowych webhooków: osiem prób w ciągu około 27,5 godziny, a odpowiedź 2xx w ciągu 15 sekund liczy się jako sukces. W przeciwieństwie do punktu końcowego adres URL wywołania zwrotnego nigdy nie jest wstrzymywany.

Dostarczanie odbywa się co najmniej raz i bez gwarancji kolejności. Usuwaj duplikaty na podstawie nagłówka webhook-id i sortuj według pola timestamp w ładunku.

Znajdź i odtwórz ponownie nieudane wywołania zwrotne

Karta Direct callbacks w sekcji Webhooks w panelu oraz List callback delivery attempts pokazują próby wywołań zwrotnych w obszarze roboczym, od najnowszych, z adresem URL, statusem zwróconym przez Twój odbiornik i opóźnieniem. Próby są przechowywane przez trzy dni.

Replay failed callback deliveries dodaje do kolejki jeszcze jedną próbę dla każdego zdarzenia, którego wywołania zwrotne nie powiodły się w wybranym przez Ciebie przedziale czasu, tak jak ponowne odtwarzanie dostarczeń do punktów końcowych robi to dla punktów końcowych. Zdarzenie, które w tym przedziale zostało też dostarczone pomyślnie, jest pomijane. Sukces poza przedziałem się nie liczy, więc takie zdarzenie zostanie wysłane ponownie. Jedno ponowne odtwarzanie wysyła najwyżej 10 000 najstarszych nieudanych zdarzeń z przedziału; po dłuższej awarii odtwórz ponownie pozostałe, ustawiając późniejszy czas początkowy.

Ponowne odtwarzanie wysyła zdarzenia na adres URL zapisany w nieudanych próbach, a nie do Twoich punktów końcowych webhooków ani na bieżący adres URL profilu. Pozwala odzyskać dane po awarii Twojego odbiornika. Nie odzyska wiadomości wysłanej na błędny adres URL, więc wyślij taką wiadomość ponownie. Ponowne odtworzenia wliczają się do tego samego dziennego limitu co ponowne odtworzenia dla punktów końcowych.

Dalsze kroki

Przejdź do dokumentacji, przewodników i przykładów dotyczących tego tematu.