लोकलहोस्ट पर व्हाट्सएप क्लाउड एपीआई वेबहुक का परीक्षण करने के लिए, HTTPS के माध्यम से अपने स्थानीय एंडपॉइंट को उजागर करें, मेटा की GET सत्यापन चुनौती को लागू करें, फिर प्रत्येक पोस्ट अनुरोध के X-Hub-Signature-256 को रॉ बॉडी के विरुद्ध सत्यापित करें। अपने मेटा ऐप में टनल यूआरएल रजिस्टर करें, messages के लिए व्हाट्सएप बिजनेस अकाउंट की सदस्यता लें, और बिना तैनात किए वास्तविक पेलोड प्राप्त करने के लिए एक परीक्षण संदेश भेजें।
व्हाट्सएप वेबहुक दो अलग-अलग सत्यापन प्रवाह का उपयोग करते हैं
सबसे महत्वपूर्ण अंतर यह है कि वेबहुक सेटअप और वेबहुक डिलीवरी को अलग-अलग तरीके से प्रमाणित किया जाता है। सेटअप के दौरान, मेटा एक भेजता हैप्राप्त करेंअनुरोध जिसमें शामिल हैhub.mode,hub.verify_token, औरhub.challenge. आपका समापन बिंदु सत्यापित टोकन की तुलना करता है और चुनौती को सादे पाठ के रूप में लौटाता है। बाद में, इवेंट डिलीवरी होती हैपोस्टअनुरोध; इन्हें आपके मेटा ऐप सीक्रेट के साथ बनाए गए एचएमएसी हस्ताक्षर को मान्य करके प्रमाणित किया जाना चाहिए।
एक सत्यापित टोकन आपके द्वारा चुनी गई एक यादृच्छिक स्ट्रिंग है; यह व्हाट्सएप एक्सेस टोकन नहीं है और न ही ऐप सीक्रेट है। चुनौती लौटाने से कॉलबैक समापन बिंदु का नियंत्रण सिद्ध होता है। यह भविष्य के POST अनुरोधों को प्रमाणित नहीं करता है. मेटाआधिकारिक व्हाट्सएप वेबहुक गाइडकॉलबैक कॉन्फ़िगरेशन, सब्सक्रिप्शन और वेबहुक फ़ील्ड को कवर करता है।
एक Next.js ऐप राउटर एंडपॉइंट बनाएं
नीचे दिया गया मार्ग दोनों चरणों को संभालता है। के साथ POST डेटा पढ़नाrequest.text() हस्ताक्षर सत्यापन के लिए आवश्यक सटीक बाइट्स सुरक्षित रखता है।
// app/api/webhooks/whatsapp/route.ts
import crypto from 'node:crypto';
import { NextRequest } from 'next/server';
export const runtime = 'nodejs';
export async function GET(request: NextRequest) {
const mode = request.nextUrl.searchParams.get('hub.mode');
const token = request.nextUrl.searchParams.get('hub.verify_token');
const challenge = request.nextUrl.searchParams.get('hub.challenge');
if (mode === 'subscribe' && token === process.env.META_VERIFY_TOKEN) {
return new Response(challenge ?? '', { status: 200 });
}
return new Response('Forbidden', { status: 403 });
}
export async function POST(request: Request) {
const rawBody = await request.text();
const supplied = request.headers.get('x-hub-signature-256') ?? '';
const expected = 'sha256=' + crypto
.createHmac('sha256', process.env.META_APP_SECRET!)
.update(rawBody)
.digest('hex');
const a = Buffer.from(supplied);
const b = Buffer.from(expected);
if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
return new Response('Invalid signature', { status: 401 });
}
const payload = JSON.parse(rawBody);
await enqueueWhatsAppPayload(payload);
return new Response('EVENT_RECEIVED', { status: 200 });
}कॉल न करेंrequest.json()और फिर HMAC के लिए JSON का पुनर्निर्माण करें। व्हाईटस्पेस, एस्केपिंग, या कुंजी क्रम बदल सकता है, जिससे एक अलग डाइजेस्ट उत्पन्न हो सकता है। यदि आप एक्सप्रेस का उपयोग करते हैं, तो एक कैप्चर करेंBufferवैश्विक JSON पार्सर से पहले। सामान्यवेबहुक हस्ताक्षर मार्गदर्शिका सभी फ़्रेमवर्क में रॉ-बॉडी हैंडलिंग की व्याख्या करता है।
एक सुरंग प्रारंभ करें और कॉलबैक कॉन्फ़िगर करें
- Next.js ऐप को स्थानीय रूप से चलाएं, सामान्य रूप से पोर्ट 3000 पर
npm run devके साथ। - एक अलग टर्मिनल में
npx portpreview 3000चलाएं। - सेट करें
META_VERIFY_TOKENएक यादृच्छिक मान पर औरMETA_APP_SECRETमेटा की ऐप सेटिंग से ऐप सीक्रेट पर जाएं। - मेटा डेवलपर डैशबोर्ड में, व्हाट्सएप उत्पाद का कॉन्फ़िगरेशन पृष्ठ खोलें।
- कॉलबैक URL को
https://YOUR-TUNNEL.portpreview.dev/api/webhooks/whatsappऔर वही सत्यापित टोकन दर्ज करें। - सत्यापन सफल होने के बाद,
messagesफ़ील्ड।
सुरंग को GET चुनौती और बाद की POST डिलीवरी दोनों के दौरान सक्रिय रहना चाहिए। पुराने सत्र से कॉपी किया गया यूआरएल हल हो सकता है लेकिन अब आपकी मशीन पर अग्रेषित नहीं किया जा सकता है, इसलिए जब भी स्थानीय सुरंग बदलती है तो सटीक कॉलबैक की पुष्टि करें।
GET चुनौती का स्वतंत्र रूप से परीक्षण करें
डैशबोर्ड का उपयोग करने से पहले, अनुरोध को स्थानीय रूप से पुन: उत्पन्न करें:
curl -i \
"http://localhost:3000/api/webhooks/whatsapp?hub.mode=subscribe&hub.verify_token=${META_VERIFY_TOKEN}&hub.challenge=123456"एक सही प्रतिक्रिया बॉडी के साथ स्थिति 200 है 123456, JSON नहीं और नहीं"123456"उद्धरण चिह्नों के साथ। यदि टोकन गलत है, तो 403 उपयुक्त है। क्वेरी पैरामीटर लॉग न करें क्योंकि सत्यापित टोकन वहां दिखाई देता है।
व्यावसायिक तर्क लिखने से पहले एक संदेश पेलोड को समझें
व्हाट्सएप डेटा को कई स्तरों तक गहराई से लपेटता है। एक सामान्य अधिसूचना में object: "whatsapp_business_account", एकentryसरणी, एकchangesसरणी, और एक परिवर्तन जिसकाfieldहैmessages. अंदरvalue, आने वाली उपयोगकर्ता सामग्री में दिखाई देती हैmessages; आपके द्वारा भेजे गए संदेशों की डिलीवरी, पढ़ने और विफलता अपडेट में दिखाई देते हैंstatuses.
for (const entry of payload.entry ?? []) {
for (const change of entry.changes ?? []) {
if (change.field !== 'messages') continue;
for (const message of change.value.messages ?? []) {
await handleInboundMessage({
id: message.id,
from: message.from,
type: message.type,
text: message.text?.body,
});
}
for (const status of change.value.statuses ?? []) {
await updateDeliveryStatus(status.id, status.status);
}
}
}यह न मानें कि प्रत्येक अधिसूचना में एक टेक्स्ट संदेश होता है। छवियाँ, ऑडियो, दस्तावेज़, स्थान, इंटरैक्टिव उत्तर, सिस्टम संदेश और केवल-स्थिति पेलोड के अलग-अलग आकार होते हैं। डिस्पैचर को द्वारा कुंजीबद्ध करके रखेंmessage.type, वैकल्पिक फ़ील्ड को मान्य करें, और अज्ञात ईवेंट प्रकारों को क्रैश होने के बजाय समीक्षा के लिए बनाए रखें।
POST हस्ताक्षर को सही ढंग से सत्यापित करें
दX-Hub-Signature-256मान फॉर्म का उपयोग करता हैsha256=<hex digest>. का उपयोग करके कच्चे अनुरोध बाइट्स पर HMAC-SHA256 की गणना करेंमेटा ऐप सीक्रेट. ग्राफ एपीआई कॉल के लिए स्थायी या अस्थायी व्हाट्सएप एक्सेस टोकन का उपयोग किया जाता है; यह HMAC कुंजी नहीं है. निरंतर-समय तुलना का उपयोग करें और गुम हस्ताक्षर को अस्वीकार करें।
स्थानीय सत्यापन सक्षम रखें। जो कोई भी सुरंग यूआरएल सीखता है वह उस पर मनमाना JSON पोस्ट कर सकता है। सत्यापन के बिना, एक जाली घटना स्वचालित उत्तरों को ट्रिगर कर सकती है, सीआरएम रिकॉर्ड को बदल सकती है, या ग्राहक स्थिति को उजागर कर सकती है। यदि ऐप सीक्रेट गलती से प्रतिबद्ध, मुद्रित या साझा किया गया हो तो उसे घुमाएँ।
जल्दी से स्वीकार करें और संदेशों को डुप्लिकेट करें
ईवेंट को प्रमाणित करने और स्थायी रूप से कतारबद्ध करने के बाद 200 लौटाएँ। मीडिया डाउनलोड करते समय, एलएलएम पर कॉल करते समय, या कई सेवाओं को अपडेट करते समय प्रतीक्षा न करें। पावती विफल होने पर प्रदाता डिलीवरी का पुनः प्रयास करते हैं, और नेटवर्क अस्पष्टता का मतलब है कि डुप्लिकेट सामान्य हैं।
व्हाट्सएप संदेश का उपयोग करें idइनबाउंड संदेशों और स्टेटस ऑब्जेक्ट के लिए निष्क्रियता कुंजी के रूप में। संसाधित आईडी के चारों ओर एक अद्वितीय बाधा डालें। स्थिति परिवर्तन वैध रूप से भेजे गए से वितरित से पढ़ने तक की प्रगति कर सकता है, इसलिए बाद की स्थिति को छोड़े बिना प्रत्येक प्रासंगिक संक्रमण को डुप्लिकेट करें।
व्हाट्सएप वेबहुक सेटअप की समस्या का निवारण करें
कॉलबैक यूआरएल सत्यापित नहीं किया जा सका
सार्वजनिक URL के माध्यम से GET रूट का परीक्षण करें। सुनिश्चित करें कि यह GET स्वीकार करता है, सटीक सत्यापित टोकन की तुलना करता है, और केवल चुनौती के साथ प्रतिक्रिया करता है। रीडायरेक्ट, ऑथ मिडलवेयर, लोकेल रीराइट, या JSON रैपर सत्यापन को तोड़ सकते हैं। पुष्टि करें कि पर्यावरण चर चल रही डेव प्रक्रिया द्वारा लोड किया गया है।
सत्यापन सफल हुआ लेकिन कोई संदेश नहीं आया
कॉलबैक सत्यापन अकेले व्हाट्सएप बिजनेस अकाउंट को फ़ील्ड में सब्सक्राइब नहीं करता है। डैशबोर्ड में messages सदस्यता की पुष्टि करें और यह कि फ़ोन नंबर अपेक्षित ऐप और खाते का है। यदि ऐप अभी भी विकास मोड में है तो किसी स्वीकृत प्राप्तकर्ता से एक संदेश भेजें।
प्रत्येक पोस्ट हस्ताक्षर सत्यापन में विफल रहता है
सामान्य कारणों में ऐप सीक्रेट के बजाय एक्सेस टोकन का उपयोग करना, हैशिंग पार्स किए गए JSON, sha256= उपसर्ग को छोड़ना, या विभिन्न एन्कोडिंग की तुलना करना शामिल है। बॉडी की लंबाई लॉग करें और हेडर मौजूद है या नहीं, लेकिन कभी भी गुप्त या पूर्ण ग्राहक पेलोड प्रिंट न करें।
पाठ संदेश काम करते हैं लेकिन मीडिया प्रबंधन विफल रहता है
मीडिया सूचनाओं में एक आईडी होती है, जरूरी नहीं कि फ़ाइल बाइट्स हों। वैध एक्सेस टोकन के साथ ग्राफ़ एपीआई के माध्यम से मीडिया प्राप्त करें, फिर इसे डाउनलोड करें। उस धीमे वर्कफ़्लो को वेबहुक पावती पथ से बाहर रखें।
स्थानीय समापन बिंदु डुप्लिकेट ईवेंट देखता है
प्रतिक्रिया स्थिति और विलंबता का निरीक्षण करें, टिकाऊ निष्क्रियता जोड़ें, और प्रत्येक फिक्स के बाद एक कैप्चर किए गए ईवेंट को दोबारा चलाएं। वेबहुक रीप्ले गाइड दिखाता है कि प्रत्येक कोड परिवर्तन के लिए एक नया वास्तविक संदेश भेजने से कैसे बचें।
स्थानीय परीक्षणों के दौरान ग्राहक डेटा को सुरक्षित रखें
- जहां संभव हो परीक्षण फ़ोन नंबर और सिंथेटिक वार्तालाप का उपयोग करें।
- लॉग से फोन नंबर, संदेश निकाय, मीडिया यूआरएल, संपर्क और प्रोफ़ाइल नाम संपादित करें।
- ऐप सीक्रेट स्टोर करें, टोकन तक पहुंचें, और टोकन को केवल अनदेखा पर्यावरण फ़ाइलों या गुप्त प्रबंधक में सत्यापित करें।
- यह प्रतिबंधित करें कि टनल कैप्चर कौन देख सकता है और डिबगिंग सत्र के बाद उन्हें हटा दें।
- व्यावसायिक कार्यों को निष्पादित करने से पहले ऑब्जेक्ट, फ़ील्ड और खाता पहचानकर्ताओं को मान्य करें।
एक सुरंग तेजी से पुनरावृत्ति करती है, लेकिन यह डेवलपर मशीन में उत्पादन-आकार का व्यक्तिगत डेटा भी लाती है। वास्तविक उपयोगकर्ताओं के साथ परीक्षण करने से पहले सुरंग सुरक्षा जांच सूची में नियंत्रण लागू करें।