Konfiguracja webhooków

Skonfiguruj webhooki, aby otrzymywać powiadomienia w czasie rzeczywistym o wiadomościach, statusach doręczeń i zdarzeniach kampanii.

message.received - Wiadomość przychodząca

message.sent - Wiadomość wychodząca wysłana

message.delivered - Dostarczenie potwierdzone

message.read - Potwierdzenie przeczytania

message.failed - Dostarczenie nie powiodło się

campaign.completed - Kampania zakończona

link.clicked - Kliknięcie śledzonego linku

Występuje zdarzenie (np. odebrano wiadomość)

SendSeven wysyła żądanie HTTP POST na Twój adres URL

Jeśli brak odpowiedzi 200, ponawiamy z wykładniczym opóźnieniem

Events: Wybierz, które zdarzenia chcesz otrzymywać

Unikalne ID zdarzenia (używaj do deduplikacji)

Ciąg z typem zdarzenia (np. message.received)

Znacznik czasu ISO 8601 wskazujący, kiedy wystąpiło zdarzenie

Payload właściwy dla zdarzenia (różni się w zależności od typu zdarzenia)

Pokaż przykład z załącznikiem multimedialnym

Tablica attachments pojawia się tylko wtedy, gdy wiadomość zawiera media. Każdy załącznik ma unikalne id, content_type, file_size oraz dwa adresy URL do pobrania. Obsługiwane typy: image, video, audio, document, sticker.

url - stabilny endpoint API. Wymaga uwierzytelnienia (token API lub token sesji). Nigdy nie wygasa.

signed_url - wstępnie podpisany adres URL GCS. Nie wymaga uwierzytelnienia. Wygasa po 24 godzinach.

Jeśli pobranie mediów z platformy się nie uda, surowe dane platformy są przekazywane ze znacznikiem "source": "platform" zamiast wzbogaconych pól. Nie dotyczy to typów innych niż pliki (location, contacts, reactions).

Każde zdarzenie zawierające obiekt kontaktu zawiera również tablicę contact_methods[] wymieniającą wszystkie identyfikatory kontaktu (podstawowy na początku). Pola phone i email na najwyższym poziomie są zachowane dla zachowania wstecznej kompatybilności.

Wybory szybkiej odpowiedzi i listy docierają jako message_type "button". Podpis jest w "text", a strukturowany obiekt "meta.button" niesie id i payload, co umożliwia routowanie wyboru bez analizowania tekstu.

Pokaż przykład z kliknięciem przycisku (szybka odpowiedź / lista)

Stabilny identyfikator przycisku zdefiniowany podczas wysyłania wiadomości.

Payload zwrocony przez kanał (odpowiada id dla szybkich odpowiedzi).

Czytelny podpis, który użytkownik widział i kliknął.

Wiadomości wychodzące z załącznikami plikowymi zawierają ten sam wzbogacony schemat załącznika (id, url, signed_url, content_type, file_size) co wiadomości przychodzące.

Pole error znajduje się na poziomie data (nie wewnątrz message.meta). Dołączane są również pełne obiekty conversation i contact.

Zdarzenia aktualizacji statusu (delivered, read) używają uproszczonego obiektu conversation, bez bot_session_id i bez pól ze znacznikami czasu last_*_at. Obiekt contact_method nie jest dołączany.

Obiekty conversation dla e-maili zawierają dodatkowe pola: email_integration_id i email_thread_id dla kontekstu wątku.

Zdarzenie reopened zawiera mniej pól rozmowy niż pozostałe zdarzenia rozmów (bez bot_session_id, bez znaczników czasu last_*_at i bez subject).

contact.updated ma tę samą strukturę co contact.created. Rozróżnia je pole z typem zdarzenia.

Pobierz surową treść żądania (przed parsowaniem JSON)

Oblicz HMAC-SHA256 przy użyciu klucza tajnego webhooka

Dopisz na początku sha256= i porównaj z nagłówkiem X-Webhook-Signature

Użyj porównania odpornego na ataki czasowe (timing-safe)

Twój adres URL jest publicznie dostępny (nie localhost)

Certyfikat SSL jest ważny (nie samopodpisany)

Zapora sieciowa nie blokuje adresów IP SendSeven

Używanie sparsowanego JSON zamiast surowej treści

Nieprawidłowy klucz tajny webhooka (skopiuj ponownie z ustawień)

Problemy z kodowaniem (upewnij się, że UTF-8)

Zapisz ID zdarzenia i sprawdzaj duplikaty przed przetworzeniem

Odpowiadaj kodem 200 jak najszybciej (przetwarzaj asynchronicznie)

Webhooki to wywołania zwrotne HTTP, których SendSeven używa, aby przesyłać zdarzenia do Twojej aplikacji w czasie rzeczywistym. Zamiast odpytywać REST API, Twój endpoint od razu dostaje powiadomienie, gdy dzieje się coś ważnego: przychodzi wiadomość, kończy się rozmowa, powstaje nowy kontakt albo zmienia się status doręczenia. Każde żądanie webhooka jest podpisane HMAC ze względów bezpieczeństwa i w razie niepowodzenia ponawiane automatycznie z wykładniczym opóźnieniem, dzięki czemu żadne zdarzenie nie ginie.

Konto SendSeven z co najmniej jednym połączonym kanałem

Publiczny endpoint HTTPS, który może odbierać żądania HTTP POST

Ważny certyfikat SSL (Let's Encrypt świetnie się sprawdza)

Strona Webhooks w panelu SendSeven z wyróżnionym przyciskiem Add Endpoint

Okno Add Endpoint z polem adresu URL HTTPS i wyborem subskrybowanych zdarzeń w SendSeven

Events: wybierz, które zdarzenia chcesz otrzymywać (dostępnych 16)

Authorization Header (opcjonalnie): własny nagłówek uwierzytelniający wysyłany z każdym dostarczeniem

Przez API możesz też skonfigurować: retry_strategy (exponential/linear/none), max_retries (domyślnie 8, maks. 15) oraz timeout_seconds (domyślnie 30, zakres 5–60)

Okno Webhook Created Successfully z kluczem tajnym i przyciskiem Copy

Strona szczegółów webhooka w SendSeven z adresem URL endpointu, subskrybowanymi zdarzeniami, historią dostarczeń i statusem działania

Automatycznie przy tworzeniu webhooka w panelu

Automatycznie przy tworzeniu webhooka przez API (POST /api/v1/webhook-endpoints)

Automatycznie przy zmianie adresu URL webhooka

Na żądanie przez endpoint weryfikacyjny (POST /api/v1/webhook-endpoints/{id}/verify)

1. Utwórz punkt końcowy webhook
2. Zarejestruj webhook w SendSeven
3. Wybierz typy zdarzeń do odbierania
4. Obsłuż wyzwanie weryfikacji webhook
5. Zweryfikuj podpis webhook
6. Obsłuż przychodzące zdarzenia
7. Przetestuj z przykładowymi zdarzeniami