Konfiguracja webhooka

Webhook to adres na Państwa serwerze, pod który 2Mail wysyła komunikat, gdy tylko coś stanie się z e-mailem: został dostarczony, odbity, otwarty. Dzięki temu sklep internetowy lub CRM w ciągu kilku sekund wie, co stało się z wiadomością, bez zaglądania do panelu.

Co będzie potrzebne

• adres na Państwa serwerze dostępny przez https, który może przyjmować żądania; webhook bez szyfrowania nie zostanie zaakceptowany
• fragment kodu pod tym adresem, który przetwarza dane
• uprawnienia administratora na koncie 2mail

Krok 1: utworzenie webhooka

1. Proszę otworzyć w panelu sekcję z webhookami i utworzyć nowy.
2. Wpisać adres swojego endpointu.
3. Wybrać zdarzenia, które chcą Państwo otrzymywać: dostarczenie, odbicie, otwarcie albo ich kombinację. Warto zacząć od odbić — na to zdarzenie trzeba zareagować najszybciej.
4. Zapisać. Panel pokaże tajny klucz, którym podpisywane jest każde wywołanie. Należy zapisać go w konfiguracji aplikacji.

Krok 2: weryfikacja podpisu

Każdy może wysłać żądanie na Państwa adres. Dlatego każde wywołanie z 2Mail ma w nagłówku podpis obliczony tajnym kluczem na podstawie treści. Proszę obliczyć ten podpis ponownie po swojej stronie i odrzucać żądania, w których się nie zgadza. Tego kroku nie wolno pomijać: bez weryfikacji ktoś z zewnątrz może wmówić Państwa systemowi, że wiadomość się odbiła.

Krok 3: szybka odpowiedź

Należy od razu odpowiedzieć kodem statusu z zakresu 200, a dane przetworzyć później, na przykład przez kolejkę. Jeśli przetwarzanie trwa zbyt długo albo odpowiedzą Państwo błędem, 2Mail uzna wywołanie za nieudane i spróbuje ponownie później. Kod powinien umieć przyjąć ten sam komunikat dwa razy bez podwójnych działań: do rozpoznawania powtórzeń proszę używać identyfikatora wiadomości.

Krok 4: test

Proszę wysłać wiadomość testową na adres, którym Państwo zarządzają, i sprawdzić, czy zdarzenie dostarczenia dociera do endpointu. Odbicie można przetestować adresem, który na pewno nie istnieje, w domenie, która istnieje. Panel pokazuje dla każdego webhooka ostatnie wywołania wraz z odpowiedzią Państwa serwera — od razu widać, czy endpoint zwrócił coś innego niż 200.

Co można z tym zrobić

• Przy hard bounce oznaczyć adres w CRM-ie, aby handlowiec przestał go używać.
• Przy dostarczeniu pokazać w historii zamówienia, że potwierdzenie dotarło — to oszczędza telefonów.
• Przy otwarciu zaplanować zadanie follow-up, na przykład po wysłaniu oferty.

Gdzie pojawiają się problemy

• Brak wywołań — adres jest dostępny tylko wewnętrznie albo zapora sieciowa blokuje żądania z zewnątrz.
• Podpis nigdy się nie zgadza — obliczają go Państwo na podstawie zmienionej treści; należy użyć surowej treści żądania.
• Podwójne działania — endpoint odpowiada zbyt wolno i dlatego otrzymuje powtórzenia.

Webhooki są częścią API e-mail; jeśli aplikacja ma też wysyłać pocztę, pierwszym krokiem jest utworzenie klucza API.

Coś nie działa?

Prosimy podać nam przez stronę kontaktową adres endpointu i godzinę testu. Pokażemy, co odpowiedział nam Państwa serwer.