Cara menerima pesan WhatsApp dan komentar media sosial pelanggan Anda lewat webhook
Setiap koneksi mendapatkan webhook sendiri untuk pesan WhatsApp atau komentar media sosial pelanggan Anda melalui Partner API easyCoexistence. Pesan WhatsApp dikirim langsung dari Meta ke URL tersebut, ditandatangani dengan secret aplikasi Tech Provider, bukan secret yang Anda pegang, sehingga secret acak panjang di path URL berfungsi untuk mengautentikasinya. Komentar dan DM Instagram serta Facebook, dan komentar TikTok, diteruskan begitu tiba, ditandatangani per akun dengan X-EC-Signature.
Panjang maksimum Meta untuk URL callback alternatif yang mengirim pesan sebuah nomor ke endpoint Anda.
Berapa lama Meta mencoba kembali webhook WhatsApp yang tidak diterima endpoint Anda, dengan frekuensi yang semakin jarang, yang dapat menghasilkan duplikat.
Jaringan Meta; pencarian rute whois untuknya mencantumkan alamat tempat webhook WhatsApp berasal, yang diubah Meta secara berkala.
Ukuran terbesar payload webhook WhatsApp menurut Meta.
Usia setelah timestamp bertanda tangan sebuah event yang diteruskan harus ditolak, dengan HMAC dibandingkan dalam waktu konstan.
Bagaimana setiap koneksi mendapatkan tujuannya sendiri?
Melalui satu panggilan per resource. Nomor WhatsApp menggunakan PUT /connections/{id}/webhook dengan url dan verify_token, atau pasangan yang sama sebagai webhook_url dan webhook_verify_token pada sesi koneksinya, sehingga nomor itu merutekan ke Anda sejak menit pertama. Akun media sosial menggunakan PUT /channels/{id}/webhook setelah terhubung. url bernilai null pada salah satu jalur mematikan pengiriman. Kedua jalur berbeda dalam hal siapa yang mengirim dan cara Anda mengautentikasi:
| 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 |
Bagaimana cara mengarahkan pesan sebuah nomor ke endpoint Anda?
Berikan URL HTTPS yang path-nya berisi secret acak panjang, plus verify token: webhook_verify_token pada sesi koneksi, 8 hingga 200 karakter, atau verify_token pada PUT. Meta segera memeriksa URL dengan GET yang membawa hub.mode=subscribe, hub.verify_token dan hub.challenge, dan endpoint Anda harus menjawab dengan nilai hub.challenge ketika token cocok. Jika handshake ini gagal, PUT mengembalikan 502 meta_rejected beserta pesan Meta sendiri; pada sesi koneksi, nomor tetap terhubung, dan last_error sesi menjelaskan mengapa URL tidak diterapkan.
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
});Mengapa tanda tangan Meta tidak bisa diperiksa, dan apa penggantinya?
Meta menandatangani setiap pengiriman dengan X-Hub-Signature-256, yaitu HMAC-SHA256 dari payload dengan kunci App Secret aplikasi penerima. Untuk nomor pelanggan Anda, aplikasi itu adalah aplikasi Tech Provider easyCoexistence, dan secret-nya tidak pernah dibagikan, sehingga header tersebut tidak dapat diverifikasi di sisi Anda. Secret acak panjang di path URL menjadi kredensialnya: bandingkan dalam waktu konstan dan tolak selain itu. Sebagai lapisan kedua, masukkan ke daftar izin rute yang terdaftar di AS32934 milik Meta dan perbarui daftar itu, karena Meta mengubah alamat IP-nya secara berkala.
Webhook WhatsApp mana yang sampai ke URL Anda?
Bidang yang dapat dibawa oleh URL callback alternatif Meta: messages, untuk apa yang dikirim pelanggan dan status dari apa yang Anda kirim; smb_message_echoes, untuk apa yang dikirim bisnis dari aplikasi WhatsApp Business; dan riwayat dari impor satu kali serta smb_app_state_sync. Meta tidak pernah mengirim webhook template, atau webhook akun seperti account_update, ke override. Webhook tersebut justru diterima oleh callback easyCoexistence, itulah sebabnya tinjauan template dibaca melalui polling dan penolakan sampai ke Anda sebagai event status.
- Tujuan diatur pada WhatsApp Business Account, sehingga dua nomor dalam satu akun berbagi tujuan itu: lakukan perutean berdasarkan value.metadata.
phone_number_id. - Media datang sebagai ID; ambil file dari Meta dengan token pelanggan dari panggilan kredensial.
- Payload dapat mencapai 3 MB, jadi naikkan batas ukuran body yang diatur di bawah itu.
Seperti apa event sosial yang diteruskan?
POST dengan Content-Type application/json dan header X-EC-Signature, berisi empat kunci: platform; account_id, yaitu ID saluran yang digunakan Partner API; external_id, yaitu ID akun di jaringan tersebut; dan entry. Untuk Instagram dan Facebook, entry adalah entry webhook Meta tanpa perubahan, dengan changes untuk komentar dan mention serta messaging untuk DM. Untuk TikTok, isinya event comment.update dengan kontennya sudah diurai, dan comment_id, video_id serta parent_comment_id sebagai string, sehingga ID 64-bit tidak dibulatkan.
- Akun Instagram berlangganan comments, messages, dan mentions; Halaman Facebook berlangganan feed, messages, dan mention; TikTok mengirim comment.update.
- easyCoexistence tidak menerima event komentar dari YouTube atau LinkedIn: PUT mereka menjawab 400
not_supported, dan komentar mereka dibaca melalui API masing-masing jaringan dengan kredensial. - Pengiriman tidak membawa header X-EC-Event atau X-EC-Delivery, jadi lakukan deduplikasi dengan ID milik jaringan, seperti ID komentar atau mid pesan.
{
"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>" }
}
}
]
}
}Bagaimana cara memverifikasi X-EC-Signature, langkah demi langkah?
Dengan signing_secret yang dikembalikan PUT /channels/{id}/webhook, yang hanya ditampilkan sekali dan unik untuk akun itu. Header berbunyi t=<unix>,v1=<hex>. Lalu, untuk setiap pengiriman:
- Baca body permintaan mentah sebagai byte, sebelum parsing JSON apa pun.
- Pisahkan header berdasarkan koma menjadi t, waktu Unix dalam detik, dan v1, digest hex.
- Tolak pengiriman jika t berselisih lebih dari 5 menit dari jam Anda.
- Hitung HMAC-SHA256 atas t, titik, dan body mentah, dengan kunci secret akun itu, sebagai hex.
- Bandingkan dengan v1 dalam waktu konstan, lalu jawab 2xx dan masukkan pekerjaannya ke antrean.
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);
});Apa yang terjadi saat tidak ada tujuan yang diatur?
Tidak ada yang sampai kepada Anda, dan tidak ada yang menunggu untuk dikirim nanti. Nomor tanpa webhook_url dialihkan ke callback easyCoexistence, di mana pesannya dibuang tanpa disimpan, dan nomor itu tidak mendapatkan impor riwayat chat, yang hanya diminta setelah tujuan ada. Akun media sosial tanpa tujuan tidak diteruskan: event-nya tetap sampai ke aplikasi easyCoexistence, tetapi tidak ada yang disimpan untuk Anda. Atur setiap tujuan sebelum Anda membutuhkan lalu lintasnya.
Apa yang terjadi pada tujuan saat koneksi putus atau dihapus?
Nomor tetap menyimpan tujuannya. Ketika nomor yang terputus terhubung kembali, easyCoexistence mengatur ulang URL Anda di Meta, dan hal yang sama terjadi saat nomor yang ditangguhkan kembali aktif. Menghapus akun media sosial menghapus tujuan dan secret-nya, jadi setelah terhubung kembali, panggil PUT /channels/{id}/webhook lagi dan simpan secret yang baru. PUT itu menerbitkan secret baru setiap kali dipanggil dengan URL, dan secret lama langsung berhenti menandatangani.
Cara mengonfigurasi
- 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.
Kesalahan umum
- Memeriksa X-Hub-Signature-256 pada pengiriman WhatsApp pelanggan Anda. Meta menghitungnya dengan secret aplikasi easyCoexistence, yang tidak pernah dibagikan, sehingga pemeriksaan tidak akan pernah lolos; autentikasi dengan secret di path URL.
- Memverifikasi X-EC-Signature atas JSON yang sudah diurai. HMAC mencakup body mentah byte demi byte, dan men-serialisasi ulang mengubah byte-nya, jadi verifikasi sebelum parsing.
- Menggunakan satu secret untuk setiap saluran. Setiap akun media sosial menandatangani dengan secret-nya sendiri, dan event status dengan secret lain, jadi cari secret berdasarkan account_id.
- Melakukan pekerjaan lambat sebelum menjawab event yang diteruskan. Event dikirim sekali, menunggu 8 detik untuk jawaban Anda, dan tidak pernah dicoba ulang, jadi jawab 2xx dulu, lalu proses.
easyCoexistence merutekan pesan setiap nomor pelanggan dari Meta langsung ke server Anda, dan meneruskan komentar serta DM Instagram dan Facebook, serta komentar TikTok, ke endpoint Anda begitu tiba, ditandatangani per akun, tanpa salinan yang disimpan dan setiap koneksi dipantau 24/7. US$ 9 hingga US$ 0.75 per koneksi per bulan, turun seiring Anda menambah koneksi, dengan 3 hari pertama gratis.
Pertanyaan yang sering diajukan
Bisakah saya memverifikasi tanda tangan Meta pada pesan WhatsApp pelanggan saya?
Tidak. Meta menandatanganinya dengan secret aplikasi Tech Provider easyCoexistence, yang tidak pernah dibagikan. Autentikasi dengan secret acak panjang di path URL Anda, dan opsional rentang IP Meta.
Apakah koneksi YouTube dan LinkedIn meneruskan event komentar?
Tidak. easyCoexistence tidak menerima event komentar dari keduanya, sehingga PUT /channels/{id}/webhook menjawab 400 not_supported. Baca komentar mereka melalui API masing-masing jaringan dengan kredensial saluran.
Apakah event sosial yang diteruskan dicoba ulang jika server saya mati?
Tidak. Setiap event dikirim sekali dan tidak ada salinan yang disimpan. Pengiriman WhatsApp berbeda, karena Meta sendiri mencobanya kembali hingga 7 hari.
Apakah pesan melewati easyCoexistence?
Tidak di WhatsApp: Meta mengirim pesan sebuah nomor langsung ke webhook yang Anda atur. Komentar dan DM dari jaringan sosial diteruskan ke endpoint Anda begitu tiba, ditandatangani per akun, tanpa salinan yang disimpan.
Lanjut membaca
Hubungkan saluran pertama Anda dalam dua menit.
Tanpa menunggu peninjauan platform. Hubungkan WhatsApp, Instagram, TikTok, atau saluran lainnya, lalu minta AI Anda untuk memposting, membalas, atau membuat laporan, dan lihat hasilnya langsung.
- Gratis 3 hari
- Batalkan kapan saja
- Hanya API resmi
- Dipantau 24/7
Diverifikasi pada