Jak odbierać przez webhook wiadomości WhatsApp i komentarze z mediów społecznościowych klientów
Każde połączenie otrzymuje własny webhook dla wiadomości WhatsApp klientów lub komentarzy w mediach społecznościowych, przez Partner API easyCoexistence. Wiadomości WhatsApp trafiają od Meta prosto na ten adres URL i są podpisane sekretem aplikacji Tech Provider, a nie Twoim własnym, dlatego do ich uwierzytelnienia służy długi losowy sekret w ścieżce URL. Komentarze oraz wiadomości prywatne z Instagrama i Facebooka, a także komentarze z TikToka, są przekazywane w momencie nadejścia i podpisywane osobno dla każdego konta za pomocą nagłówka X-EC-Signature.
Maksymalna długość, jaką Meta dopuszcza dla alternatywnego adresu URL callbacku, który kieruje wiadomości numeru do Twojego endpointu.
Jak długo Meta ponawia webhook WhatsApp, którego Twój endpoint nie przyjął, z coraz rzadszymi próbami, co może powodować duplikaty.
Sieć Meta; zapytania whois o trasy do niej zawierają adresy, z których przychodzą webhooki WhatsApp, a Meta zmienia je okresowo.
Największy możliwy rozmiar treści webhooka WhatsApp według Meta.
Wiek, po którym przekazane zdarzenie z podpisanym znacznikiem czasu powinno zostać odrzucone, przy porównaniu HMAC w stałym czasie.
Jak każde połączenie otrzymuje własny adres docelowy?
Przez jedno wywołanie na zasób. Numer WhatsApp przyjmuje PUT /connections/{id}/webhook z parametrami url i verify_token albo tą samą parą jako webhook_url i webhook_verify_token w sesji połączenia, dzięki czemu numer kieruje ruch do Ciebie od pierwszej minuty. Konto w mediach społecznościowych przyjmuje PUT /channels/{id}/webhook po połączeniu. Wartość url równa null w obu przypadkach wyłącza dostarczanie. Te dwie ścieżki różnią się tym, kto dostarcza dane i jak się uwierzytelniasz:
| WhatsApp number | Instagram, Facebook, TikTok | |
|---|---|---|
| Set with | webhook_url on the session, or PUT /connections/{id}/webhook | PUT /channels/{id}/webhook, after it connects |
| Delivered by | Meta, straight to your URL | easyCoexistence, forwarding each event as it arrives |
| Body | Meta's webhook, unchanged | platform, account_id, external_id and the network's entry |
| Authenticate | A long random secret in the URL path | X-EC-Signature, keyed with the account's secret |
| Retries | Meta's own, for up to 7 days | None: one attempt |
| Copy kept | None | None |
Jak skierować wiadomości numeru do Twojego endpointu?
Podaj adres HTTPS, którego ścieżka zawiera długi losowy sekret, oraz token weryfikacyjny: webhook_verify_token w sesji połączenia, od 8 do 200 znaków, albo verify_token w PUT. Meta sprawdza adres od razu żądaniem GET z hub.mode=subscribe, hub.verify_token i hub.challenge, a Twój endpoint musi odpowiedzieć wartością hub.challenge, gdy token się zgadza. Jeśli to sprawdzenie się nie powiedzie, PUT zwraca 502 meta_rejected z komunikatem samej Meta; w sesji połączenia numer nadal się łączy, a pole last_error sesji podaje, dlaczego adres nie został zastosowany.
import express from "express";
import { timingSafeEqual } from "node:crypto";
const PATH_SECRET = process.env.WA_PATH_SECRET; // the random part of webhook_url
const VERIFY_TOKEN = process.env.WA_VERIFY_TOKEN; // the verify token you sent
const app = express();
function same(a, b) {
const x = Buffer.from(String(a)), y = Buffer.from(String(b));
return x.length === y.length && timingSafeEqual(x, y);
}
// Meta's handshake, run when the destination is set
app.get("/wa/:secret", (req, res) => {
if (!same(req.params.secret, PATH_SECRET)) return res.sendStatus(404);
if (req.query["hub.mode"] !== "subscribe" || !same(req.query["hub.verify_token"], VERIFY_TOKEN)) {
return res.sendStatus(403);
}
res.send(req.query["hub.challenge"]);
});
// Messages, echoes and the one-time import; payloads reach 3 MB
app.post("/wa/:secret", express.json({ limit: "4mb" }), (req, res) => {
if (!same(req.params.secret, PATH_SECRET)) return res.sendStatus(404);
res.sendStatus(200); // answer first: Meta retries for up to 7 days
enqueue(req.body); // deduplicate on each message id before acting
});Dlaczego nie można sprawdzić podpisu Meta i czym go zastąpić?
Meta podpisuje każdą dostawę nagłówkiem X-Hub-Signature-256, czyli HMAC-SHA256 treści, wyliczonym kluczem App Secret odbierającej aplikacji. W przypadku numerów Twoich klientów tą aplikacją jest aplikacja Tech Provider easyCoexistence, a jej sekret nigdy nie jest udostępniany, dlatego nagłówka nie da się zweryfikować po Twojej stronie. Zamiast tego poświadczeniem jest długi losowy sekret w ścieżce URL: porównaj go w stałym czasie i odrzuć wszystko inne. Jako drugą warstwę dopuść na liście tylko trasy zarejestrowane przez Meta w AS32934 i odświeżaj tę listę, bo Meta okresowo zmienia swoje adresy IP.
Które webhooki WhatsApp docierają do Twojego adresu URL?
Pola, które alternatywny adres URL callbacku Meta może przenosić: messages, czyli wiadomości od klientów i status wysłanych przez Ciebie; smb_message_echoes, czyli wiadomości wysłane przez firmę z aplikacji WhatsApp Business; oraz historia i smb_app_state_sync z jednorazowego importu. Meta nigdy nie wysyła na ten adres webhooków szablonów ani webhooków konta, takich jak account_update. Trafiają one zamiast tego do callbacku easyCoexistence, dlatego sprawdzanie statusu szablonów odbywa się przez odpytywanie, a odrzucenie szablonu dociera do Ciebie jako zdarzenie statusu.
- Adres docelowy ustawia się na koncie WhatsApp Business, więc dwa numery w jednym koncie dzielą go: kieruj ruch według value.metadata.
phone_number_id. - Multimedia przychodzą jako ID; pobierz plik z Meta tokenem klienta z wywołania poświadczeń.
- Ładunki mogą mieć do 3 MB, więc podnieś każdy limit rozmiaru treści ustawiony poniżej tej wartości.
Jak wygląda przekazane zdarzenie z mediów społecznościowych?
Żądanie POST z Content-Type application/json i nagłówkiem X-EC-Signature, zawierające cztery klucze: platform; account_id, czyli ID kanału używane przez Partner API; external_id, czyli ID konta w sieci; oraz entry. Dla Instagrama i Facebooka entry to niezmieniony wpis webhooka Meta, z changes dla komentarzy i wzmianek oraz messaging dla wiadomości prywatnych. Dla TikToka zawiera zdarzenie comment.update z przetworzoną treścią oraz comment_id, video_id i parent_comment_id jako ciągi znaków, dzięki czemu 64-bitowe ID nie zostaną zaokrąglone.
- Konta Instagram są zapisane na komentarze, wiadomości i wzmianki; strony Facebook na feed, wiadomości i wzmianki; TikTok wysyła comment.update.
- easyCoexistence nie otrzymuje zdarzeń komentarzy z YouTube ani LinkedIn: ich PUT zwraca 400
not_supported, a komentarze odczytujesz przez API każdej sieci z poświadczeniami. - Przekazania nie zawierają nagłówków X-EC-Event ani X-EC-Delivery, więc deduplikuj na podstawie identyfikatorów samej sieci, na przykład ID komentarza albo mid wiadomości.
{
"platform": "instagram",
"account_id": "<CHANNEL_ID>",
"external_id": "<INSTAGRAM_ACCOUNT_ID>",
"entry": {
"id": "<INSTAGRAM_ACCOUNT_ID>",
"time": 1793440800,
"changes": [
{
"field": "comments",
"value": {
"id": "<COMMENT_ID>",
"from": { "id": "<INSTAGRAM_SCOPED_ID>", "username": "<USERNAME>" },
"text": "<COMMENT_TEXT>",
"media": { "id": "<MEDIA_ID>", "media_product_type": "<MEDIA_PRODUCT_TYPE>" }
}
}
]
}
}Jak krok po kroku zweryfikować X-EC-Signature?
Użyj signing_secret zwróconego przez PUT /channels/{id}/webhook; jest pokazywany tylko raz i jest unikalny dla danego konta. Nagłówek ma postać t=<unix>,v1=<hex>. Następnie, dla każdej dostawy:
- Odczytaj surowe ciało żądania jako bajty, przed jakimkolwiek parsowaniem JSON.
- Podziel nagłówek po przecinkach na t, czas Unix w sekundach, oraz v1, skrót w formacie hex.
- Odrzuć dostawę, jeśli t różni się od Twojego zegara o więcej niż 5 minut.
- Oblicz HMAC-SHA256 dla ciągu: t, kropka i surowe ciało, kluczem sekretu danego konta, w formacie hex.
- Porównaj wynik z v1 w stałym czasie, potem odpowiedz 2xx i dodaj zadanie do kolejki.
import express from "express";
import { createHmac, timingSafeEqual } from "node:crypto";
const app = express();
const secrets = new Map(); // channel id -> signing_secret, kept in your database
app.post("/hooks/social", express.raw({ type: "application/json" }), (req, res) => {
const sig = Object.fromEntries(
(req.get("X-EC-Signature") ?? "").split(",").map((part) => part.split("=", 2)),
);
if (!/^\d+$/.test(sig.t ?? "") || Math.abs(Date.now() / 1000 - Number(sig.t)) > 300) {
return res.sendStatus(401); // missing or stale timestamp
}
let event;
try {
event = JSON.parse(req.body.toString("utf8")); // platform, account_id, external_id, entry
} catch {
return res.sendStatus(400);
}
const secret = secrets.get(event.account_id);
if (!secret || !sig.v1) return res.sendStatus(401);
const expected = createHmac("sha256", secret)
.update(sig.t + ".")
.update(req.body) // the raw bytes, exactly as they arrived
.digest("hex");
if (expected.length !== sig.v1.length ||
!timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1))) {
return res.sendStatus(401);
}
res.sendStatus(204); // one attempt and no retries: acknowledge, then work
enqueue(event);
});Co się dzieje, gdy nie ustawiono adresu docelowego?
Nic do Ciebie nie dociera i nic nie czeka na późniejsze wysłanie. Numer bez webhook_url przechodzi na callback easyCoexistence, gdzie jego wiadomości są pomijane bez zapisu, a import historii czatu nie jest wykonywany, bo jest zlecany dopiero po utworzeniu adresu docelowego. Konto w mediach społecznościowych bez adresu nie jest przekazywane: jego zdarzenia nadal trafiają do aplikacji easyCoexistence, ale żadne nie jest przechowywane dla Ciebie. Ustaw każdy adres docelowy, zanim będziesz potrzebować ruchu.
Co się dzieje z adresem docelowym, gdy połączenie zostanie przerwane lub usunięte?
Numer zachowuje swój adres docelowy w rejestrze. Gdy przerwany numer połączy się ponownie, easyCoexistence ustawia Twój URL w Meta na nowo; tak samo dzieje się, gdy zawieszony numer wraca. Usunięcie konta w mediach społecznościowych czyści jego adres docelowy i sekret, więc po ponownym połączeniu wywołaj PUT /channels/{id}/webhook jeszcze raz i zapisz nowy sekret. Ten PUT wystawia nowy sekret za każdym razem, gdy zostanie wywołany z adresem URL, a stary przestaje podpisywać od razu.
Jak to skonfigurować
- Put a secret in the URLChoose an HTTPS URL whose path holds a long random string, 200 characters or fewer in all, and make its GET answer Meta's hub.challenge.
- Route the number's messagesSend webhook_url and webhook_verify_token on the connect session, or PUT /connections/{id}/webhook once the number is connected.
- Turn on each social accountCall PUT /channels/{id}/webhook with your URL and store the signing_secret it returns against that channel.
- Verify, then acknowledgeCheck the path secret on WhatsApp deliveries and X-EC-Signature on forwarded ones, answer 2xx at once, then process from a queue.
Typowe błędy
- Sprawdzanie X-Hub-Signature-256 w dostawach WhatsApp od Twoich klientów. Meta liczy go kluczem App Secret easyCoexistence, który nigdy nie jest udostępniany, więc sprawdzenie nie może się udać; uwierzytelniaj sekretem w ścieżce URL.
- Weryfikowanie X-EC-Signature po sparsowaniu JSON. HMAC obejmuje surowe ciało bajt po bajcie, a ponowna serializacja zmienia bajty, więc weryfikuj przed parsowaniem.
- Używanie jednego sekretu dla wszystkich kanałów. Każde konto w mediach społecznościowych podpisuje własnym sekretem, a zdarzenia statusu innym, więc wyszukuj sekret po account_id.
- Wykonywanie wolnej pracy przed odpowiedzią na przekazane zdarzenie. Jest ono wysyłane raz, czeka 8 sekund na Twoją odpowiedź i nigdy nie jest ponawiane, więc najpierw odpowiedz 2xx, a dopiero potem przetwarzaj.
easyCoexistence kieruje wiadomości każdego numeru klienta z Meta prosto na Twój serwer i przekazuje komentarze oraz wiadomości prywatne z Instagrama i Facebooka, a także komentarze z TikToka, na Twój endpoint w momencie ich nadejścia, podpisane osobno dla każdego konta, bez zachowywania kopii i z monitorowaniem każdego połączenia 24/7. Od US$ 9 do US$ 0.75 za połączenie miesięcznie, spadając wraz z dodawaniem połączeń, z pierwszymi 3 dniami bezpłatnie.
Najczęściej zadawane pytania
Czy mogę zweryfikować podpis Meta w wiadomościach WhatsApp moich klientów?
Nie. Meta podpisuje je sekretem aplikacji Tech Provider easyCoexistence, który nigdy nie jest udostępniany. Uwierzytelniaj długim losowym sekretem w ścieżce URL, a opcjonalnie zakresami adresów IP Meta.
Czy połączenia z YouTube i LinkedIn przekazują zdarzenia komentarzy?
Nie. easyCoexistence nie otrzymuje zdarzeń komentarzy z żadnej z tych sieci, więc PUT /channels/{id}/webhook zwraca 400 not_supported. Komentarze odczytuj przez API każdej sieci z poświadczeniami kanału.
Czy przekazane zdarzenia z mediów społecznościowych są ponawiane, gdy mój serwer nie działa?
Nie. Każde jest wysyłane raz i nie zachowuje się żadnej kopii. Dostawy WhatsApp są inne, ponieważ Meta sama ponawia je przez maksymalnie 7 dni.
Czy wiadomości przechodzą przez easyCoexistence?
Nie w przypadku WhatsApp: Meta dostarcza wiadomości numeru prosto na webhook, który ustawisz. Komentarze i wiadomości prywatne z sieci społecznościowych są przekazywane na Twój endpoint w momencie nadejścia, podpisane osobno dla każdego konta, bez zachowywania kopii.
Czytaj dalej
Połącz pierwszy kanał w dwie minuty.
Bez czekania na weryfikację przez platformy. Połącz WhatsApp, Instagram, TikTok lub inny kanał, a potem poproś swoją AI o opublikowanie posta, odpowiedź lub raport i zobacz, jak działa.
- 3 dni za darmo
- Rezygnacja w każdej chwili
- Tylko oficjalne API
- Monitorowanie 24/7
Zweryfikowano w