Webhooki RCS

Webhooki RCS pozwalają odbierać zdarzenia związane z wysyłką wiadomości i aktywnością odbiorców bez cyklicznego odpytywania API.

Spis treści

• Konfiguracja
• Nagłówki bezpieczeństwa
• Przykładowy payload
• Typy zdarzeń
• Powtórzenia i ponowienia
• Dobre praktyki

Konfiguracja

Webhooki konfiguruje administrator konta w sekcji RCS -> Ustawienia.

Podczas konfiguracji należy:

1. wskazać docelowy adres URL odbierający zdarzenia
2. wybrać obsługiwane typy zdarzeń
3. zapisać konfigurację po stronie konta RCS

Adres odbiorczy powinien być publicznie dostępny przez HTTPS i gotowy do odbioru ponowień tego samego zdarzenia.

Nagłówki bezpieczeństwa

Każde wywołanie webhooka zawiera następujące nagłówki:

Nagłówek	Znaczenie
X-Confirmation-Event	Typ zdarzenia
X-Confirmation-Id	Unikalny identyfikator zdarzenia
X-Confirmation-Signature	Podpis sha256=<hex HMAC-SHA256>

Podpis jest obliczany na podstawie surowej treści żądania z użyciem sekretu integracji. Podpis należy zweryfikować przed przetworzeniem payloadu.

Przykład w Node.js:

import crypto from 'node:crypto'

const rawBody = requestBodyAsString
const signature = request.headers['x-confirmation-signature'] || ''
const expected = `sha256=${crypto
  .createHmac('sha256', integrationSecret)
  .update(rawBody)
  .digest('hex')}`

if (signature !== expected) {
  throw new Error('Invalid webhook signature')
}

Uwaga

Do weryfikacji należy użyć surowego body żądania. Parsowanie JSON przed obliczeniem HMAC może zmienić format danych i spowodować błędną walidację podpisu.

Przykładowy payload

Poniżej przykład zdarzenia akcji użytkownika:

{
  "eventId": "rcse_tY8xZb5vN0h2",
  "type": "rcs.user.action",
  "occurredAt": "2030-07-27T10:00:05.000Z",
  "data": {
    "messageId": "rcsm_01J9ZQ4ZQ9M8D2",
    "campaignId": null,
    "clientReferenceId": "order-2026-000123",
    "agentId": "google-rbm-agent-id",
    "recipient": "+48500100200",
    "action": {
      "type": "quick_reply",
      "payload": "CONFIRM",
      "text": "Potwierdź"
    }
  }
}

Znaczenie głównych pól:

• eventId jednoznacznie identyfikuje zdarzenie
• type określa rodzaj zdarzenia
• occurredAt zawiera czas wystąpienia zdarzenia
• data.messageId wskazuje wiadomość RCS
• data.campaignId wskazuje kampanię, jeśli zdarzenie pochodzi z kampanii
• data.clientReferenceId pozwala powiązać zdarzenie z zewnętrznym systemem
• data.agentId identyfikuje agenta RCS
• data.recipient zawiera numer odbiorcy
• data.action występuje dla rcs.user.action i opisuje wykonaną akcję

Typy zdarzeń

Typ zdarzenia	Opis
rcs.message.sent	Wiadomość została wysłana do operatora RCS
rcs.message.delivered	Wiadomość została dostarczona do odbiorcy
rcs.message.read	Odbiorca odczytał wiadomość
rcs.message.expired	Wiadomość wygasła przed doręczeniem lub odczytem
rcs.user.message	Odbiorca wysłał wiadomość do agenta
rcs.user.action	Odbiorca wykonał akcję, na przykład kliknął przycisk
rcs.user.unsubscribed	Odbiorca zrezygnował z komunikacji

Dla zdarzeń rcs.user.action pole action zawiera szczegóły wykonanej akcji, takie jak:

• type
• payload
• text

Powtórzenia i ponowienia

To samo zdarzenie może zostać dostarczone więcej niż raz. Odbiorca webhooka powinien działać idempotentnie.

• zapisuj eventId po poprawnym przetworzeniu zdarzenia
• ignoruj duplikaty o tym samym eventId
• kod 2xx zwracaj dopiero po zapisaniu lub trwałym obsłużeniu zdarzenia

W przypadku błędu transportowego oraz odpowiedzi 408, 429 lub 5xx API wykonuje maksymalnie trzy próby ponownego dostarczenia.

Dobre praktyki

• weryfikuj X-Confirmation-Signature przed odczytem danych biznesowych
• loguj eventId, type, messageId oraz campaignId, jeśli występuje
• obsługuj webhooki asynchronicznie, jeśli ich przetworzenie trwa dłużej
• utrzymuj endpoint odporny na duplikaty i krótkie skoki ruchu
• odpowiadaj szybko kodem 2xx, gdy zdarzenie zostało już bezpiecznie zapisane