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.failed - Dostarczenie nie powiodło się

campaign.completed - Kampania zakończona

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ć

Event type string (e.g., message.received)

ISO 8601 timestamp when the event occurred

ID of the resource that triggered the event

Event-specific payload (varies by event type)

The attachments array is only present when the message includes media. Each attachment includes a unique id, content_type, file_size, and two download URLs. Supported types: image, video, audio, document, sticker.

url — Stable API endpoint. Requires authentication (API key or session token). Never expires.

signed_url — Pre-signed GCS URL. No authentication required. Expires after 24 hours.

If the platform media download fails, the raw platform data is passed through with a "source": "platform" marker instead of the enriched fields. Non-file types (location, contacts, reactions) are not affected.

Kazde zdarzenie zawierajace obiekt kontaktu zawiera rowniez tablice contact_methods[] wymieniajaca wszystkie identyfikatory kontaktu (podstawowy na poczatku). Pola phone i email na najwyzszym poziomie sa zachowane dla zachowania wstecznej kompatybilnosci.

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

Pokaz przyklad z kliknieciem przycisku (szybka odpowiedz / lista)

Stabilny identyfikator przycisku zdefiniowany podczas wysylania wiadomosci.

Payload zwrocony przez kanal (odpowiada id dla szybkich odpowiedzi).

Czytelny podpis, ktory uzytkownik widzial i kliknal.

Outbound messages that include file attachments contain the same enriched attachment schema (id, url, signed_url, content_type, file_size) as inbound messages.

The error field is at the data level (not inside message.meta). The full conversation and contact objects are also included.

Status update events (delivered, read) use a simpler conversation object without bot_session_id or last_*_at timestamp fields. The contact_method object is not included.

Email conversation objects include additional fields: email_integration_id and email_thread_id for threading context.

The reopened event includes fewer conversation fields than other conversation events (no bot_session_id, last_*_at timestamps, or subject).

contact.updated and contact.deleted use the same structure. The event type field distinguishes between them.

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

Oblicz HMAC-SHA256 przy użyciu klucza tajnego webhooka

Porównaj z nagłówkiem X-SendSeven-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)

Webhooks are HTTP callbacks that SendSeven uses to push real-time events to your application. Instead of polling the REST API, your endpoint receives instant notifications when something important happens — a message arrives, a conversation ends, a contact is created, or delivery status changes. Each webhook request is HMAC-signed for security and automatically retried on failure with exponential backoff, ensuring no events are lost.

A SendSeven account with at least one connected channel

A public HTTPS endpoint that can receive HTTP POST requests

A valid SSL certificate (Let's Encrypt works great)

Basic understanding of REST APIs and JSON

SendSeven dashboard Webhooks page with the Add Endpoint button highlighted

Add Endpoint dialog with HTTPS URL field and event subscriptions in SendSeven

Webhook Created Successfully popup displaying the secret key with a Copy button

Webhook detail page showing endpoint URL, subscribed events, delivery history, and health status in SendSeven

Automatically when creating a webhook via the dashboard

Automatically when creating a webhook via the API (POST /api/v1/webhook-endpoints)

Automatically when the webhook URL is updated

On-demand via the verify endpoint (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