Επαναλήψεις, διπλότυπα και σειρά των webhooks του WhatsApp: πώς να τα χειριστείτε
Η Meta επαναλαμβάνει ένα webhook του WhatsApp που δεν λαμβάνει HTTP 200, αμέσως και στη συνέχεια με μειούμενη συχνότητα έως 7 ημέρες, και το απορρίπτει μετά. Οι επαναλήψεις στέλνονται σε κάθε εφαρμογή συνδεδεμένη στον λογαριασμό, γι' αυτό τα διπλότυπα είναι φυσιολογικά. Απαντήστε με 200 γρήγορα, αποκλείστε τα διπλότυπα με βάση το αναγνωριστικό μηνύματος ή το αναγνωριστικό κατάστασης μαζί με την κατάσταση, και ταξινομήστε τα γεγονότα με τα δικά τους χρονικά σημεία.
Το easyCoexistence συνδέει τον αριθμό της εφαρμογής WhatsApp Business σας με το Cloud API της Meta μέσω του Coexistence και απορροφά τις επαναλήψεις της Meta πριν τις δουν οι αυτοματισμοί σας, ώστε ένα μήνυμα που επαναλαμβάνεται να μη λαμβάνει δεύτερη απάντηση AI.
Για πόσο χρονικό διάστημα η Meta συνεχίζει να επαναλαμβάνει ένα webhook που δεν έλαβε HTTP 200, πριν το απορρίψει.
Τα περισσότερα ενημερωμένα στοιχεία η Meta τα ομαδοποιεί σε ένα POST. Η Meta δεν εγγυάται ομαδοποίηση, οπότε χειριστείτε κάθε αίτημα χωριστά.
Το μεγαλύτερο payload που μπορεί να μεταφέρει ένα POST webhook του WhatsApp.
Για πόσο χρονικό διάστημα το easyCoexistence θυμάται κάθε εισερχόμενο αναγνωριστικό μηνύματος, ώστε ένα μήνυμα που ξαναστέλνεται να μην εκτελεί αυτοματισμό δύο φορές.
Προσπάθειες ανά προώθηση στο Forward URL σας, με αναμονή 10 δευτερολέπτων για 2xx κάθε φορά, μέσα σε περίπου 33 ώρες.
Πότε η Meta επαναλαμβάνει ένα webhook του WhatsApp;
Όποτε μια παράδοση στο endpoint σας λαμβάνει κατάσταση HTTP διαφορετική από 200, ή δεν μπορεί να παραδοθεί καθόλου. Η Meta επαναλαμβάνει αμέσως, και στη συνέχεια λίγες φορές ακόμη με μειούμενη συχνότητα τις επόμενες 7 ημέρες, και απορρίπτει ό,τι δεν έχει επιβεβαιωθεί μετά. Οι επαναλήψεις στέλνονται σε κάθε εφαρμογή συνδεδεμένη στον WhatsApp Business Account για αυτό το πεδίο, γι' αυτό η Meta προειδοποιεί ότι μπορούν να δημιουργήσουν διπλές ειδοποιήσεις. Δεν υπάρχει API για ανάκτηση παλαιότερων webhooks, οπότε μια παράδοση που εξαντλεί τις 7 ημέρες της χάνεται για το σύστημά σας.
Γιατί φτάνουν διπλότυπα ακόμη και όταν ο server σας είναι υγιής;
Επειδή μια παράδοση μπορεί να πετύχει από την πλευρά σας και παρ' όλα αυτά να φαίνεται αποτυχημένη στη Meta. Ένας χειριστής που κάνει τη δουλειά του πριν απαντήσει μπορεί να ξεπεράσει τον χρόνο αναμονής της Meta, οπότε η Meta επαναλαμβάνει κάτι που έχετε ήδη επεξεργαστεί. Μια ανάπτυξη που επανεκκινεί τον server στη μέση ενός αιτήματος, ένας load balancer που επιστρέφει 502 για λίγο, ή ένα 201 ή 204 αντί για 200, μετράνε όλα ως αποτυχίες. Οι ομάδες προσθέτουν μία ακόμη περίπτωση: ένα POST μπορεί να περιέχει πολλές ενημερώσεις, οπότε ένα timeout σε μεγάλη ομάδα επιστρέφει ολόκληρη την ομάδα, συμπεριλαμβανομένων των ενημερώσεων που έχετε ήδη χειριστεί.
Με ποιο κλειδί πρέπει να αποκλείετε τα διπλότυπα;
Με τα αναγνωριστικά που ορίζει η ίδια η Meta, ανά τύπο συμβάντος, επειδή ένα μήνυμα παράγει νόμιμα πολλά webhooks. Ένα κλειδί κατάστασης χωρίς την τιμή της κατάστασης θα έριχνε τα delivered και θα τα θεωρούσε αντίγραφα του sent, ενώ ένα κλειδί κλήσης χωρίς το συμβάν θα κρατούσε μόνο το πρώτο στάδιο της κλήσης. Αποθηκεύστε τα κλειδιά με μοναδικό ευρετήριο, ώστε δύο εργαζόμενοι που χειρίζονται την ίδια επανάληψη να μην μπορούν να νικήσουν και οι δύο:
Με ποια σειρά φτάνουν τα webhooks;
Όχι απαραίτητα με τη σειρά που έγιναν τα πράγματα. Η τεκμηρίωση της Meta δεν εγγυάται σειρά, μια επαναλαμβανόμενη παράδοση φτάνει μετά από νεότερες, και μια κατάσταση μπορεί να παραλείψει ένα βήμα: η Meta στέλνει read χωρίς delivered όταν ένα μήνυμα διαβάζεται τη στιγμή που φτάνει. Γι' αυτό αποθηκεύστε τα γεγονότα με το δικό τους πεδίο χρόνου, συγκρίνετε μια κατάσταση με βάση την τάξη της και όχι με βάση τη λήψη, και αφήστε ένα μεταγενέστερο μήνυμα πελάτη να υπερισχύσει έναντι ενός παλαιότερου που έφτασε καθυστερημένα. Σε αριθμό Coexistence, η εφάπαξ εισαγωγή ιστορικού μπορεί να επικαλύπτεται με ζωντανά μηνύματα γύρω από την ένταξη, και το αναγνωριστικό μηνύματος είναι αυτό που τα αντιστοιχίζει.
Πώς είναι ένας ασφαλής χειριστής;
Τέσσερα βήματα: επαληθεύστε, απαντήστε ακριβώς 200, αποκλείστε τα διπλότυπα και στη συνέχεια εργαστείτε από μια ουρά, ώστε τίποτα αργό να μην μπαίνει ανάμεσα στο αίτημα της Meta και την απάντησή σας. Αυτή η έκδοση ελέγχει το X-Hub-Signature-256 με το δικό σας μυστικό εφαρμογής Meta. Για έναν αριθμό συνδεδεμένο μέσω του easyCoexistence, η Meta υπογράφει με το μυστικό εφαρμογής του easyCoexistence, οπότε ένας άμεσος προορισμός ταυτοποιείται με ένα μακρύ μυστικό στη διαδρομή του URL, ή αλλάζει σε διαχειριζόμενη προώθηση υπογεγραμμένη ανά αριθμό.
// meta-webhook.mjs: node meta-webhook.mjs (no dependencies)
import crypto from "node:crypto";
import http from "node:http";
const APP_SECRET = process.env.META_APP_SECRET; // the secret of the Meta app that subscribed
const seen = new Set(); // keys already accepted: a unique index in a database in production
// One key per thing that happened, so a redelivery maps to the same keys.
function keysOf(field, value) {
const keys = [];
for (const m of value.messages ?? []) keys.push(`${field}:msg:${m.id}`);
for (const s of value.statuses ?? []) keys.push(`${field}:status:${s.id}:${s.status}`);
for (const e of value.message_echoes ?? []) keys.push(`${field}:echo:${e.id}`);
for (const c of value.calls ?? []) keys.push(`${field}:call:${c.id}:${c.event}`);
return keys;
}
http.createServer((req, res) => {
const chunks = [];
req.on("data", (c) => chunks.push(c));
req.on("end", () => {
const raw = Buffer.concat(chunks);
const got = Buffer.from(String(req.headers["x-hub-signature-256"] ?? ""));
const want = Buffer.from("sha256=" + crypto.createHmac("sha256", APP_SECRET).update(raw).digest("hex"));
if (req.method !== "POST" || got.length !== want.length || !crypto.timingSafeEqual(got, want)) {
res.writeHead(401).end();
return;
}
res.writeHead(200).end(); // exactly 200, before any work
const body = JSON.parse(raw.toString("utf8"));
for (const entry of body.entry ?? []) {
for (const change of entry.changes ?? []) {
for (const key of keysOf(change.field, change.value ?? {})) {
if (seen.has(key)) continue; // a retry of something already accepted
seen.add(key);
// queue { key, field: change.field, value: change.value } for a worker here
console.log("new", key);
}
}
}
});
}).listen(process.env.PORT ?? 3000);Πώς χειρίζεται το easyCoexistence τις επαναλήψεις σε έναν συνδεδεμένο αριθμό;
Στην είσοδο, το easyCoexistence ελέγχει την υπογραφή της Meta, απαντά 200 και εκτελεί τους αυτοματισμούς μετά την απάντηση, ώστε η Meta να μην επαναλάβει επειδή μια απάντηση AI χρειάστηκε λίγα δευτερόλεπτα. Κάθε αναγνωριστικό εισερχόμενου μηνύματος διατηρείται για 7 ημέρες, το μήκος του παραθύρου επανάληψης της Meta, και ένα μήνυμα που ξαναστέλνεται αναγνωρίζεται και δεν ενεργοποιεί δεύτερη αυτόματη απάντηση.
Στην έξοδο προς το Forward URL σας, κάθε αλλαγή της Meta γίνεται μία παράδοση με αναγνωριστικό στο X-EC-Delivery που μένει το ίδιο σε όλες τις επαναλήψεις προώθησης: 7 προσπάθειες σε περίπου 33 ώρες, με αναμονή 10 δευτερολέπτων για 2xx κάθε φορά. Μια αλλαγή που η ίδια η Meta ξαναστέλνει προωθείται ξανά με νέο αναγνωριστικό παράδοσης, οπότε αποκλείστε και με βάση τα αναγνωριστικά της Meta μέσα στο value.
Συνηθισμένα λάθη
- Αποκλεισμός καταστάσεων μόνο με βάση το id. Τα sent, delivered και read μοιράζονται το wamid, οπότε το κλειδί χρειάζεται και την κατάσταση.
- Επεξεργασία πριν από την απάντηση. Ένας αργός χειριστής κάνει τη Meta να επαναλαμβάνει δουλειά που έχετε ήδη κάνει. Επιστρέψτε πρώτα 200 και εργαστείτε από μια ουρά.
- Επιστροφή 201 ή 204. Η τεκμηρίωση της Meta αντιμετωπίζει κάθε κατάσταση εκτός από 200 ως αποτυχημένη παράδοση και την επαναλαμβάνει.
- Αποκλεισμός προωθήσεων μόνο με το X-EC-Delivery. Μια αλλαγή που ξαναστέλνει η Meta φτάνει με νέο αναγνωριστικό παράδοσης, οπότε κρατήστε τα αναγνωριστικά της Meta ως δεύτερο κλειδί.
Οι προωθήσεις στον server σας υπογράφονται, μπαίνουν σε ουρά και επαναλαμβάνονται, και κάθε αριθμός παρακολουθείται 24/7. Από US$ 9 έως US$ 0.75 ανά αριθμό τον μήνα, μειούμενο όσο προσθέτετε αριθμούς, με τις πρώτες 3 ημέρες δωρεάν.
Συχνές ερωτήσεις
Πόσο καιρό πρέπει να κρατώ τα αναγνωριστικά που έχω δει;
Τουλάχιστον 7 ημέρες, το παράθυρο επανάληψης της Meta. Μια παράδοση που η Meta ξαναστέλνει την έκτη ημέρα πρέπει ακόμη να ταιριάζει με το κλειδί της, αλλιώς θα επεξεργαστεί ως νέα.
Τι γίνεται με τα μηνύματα των πελατών μου αν το endpoint μου είναι εκτός λειτουργίας για μέρες;
Η Meta επαναλαμβάνει έως 7 ημέρες και μετά απορρίπτει τα webhooks. Σε έναν αριθμό Coexistence, οι συνομιλίες εξακολουθούν να υπάρχουν στην εφαρμογή WhatsApp Business του τηλεφώνου, οπότε η επιχείρηση μπορεί να απαντήσει από εκεί.
Μπορώ να επαναλάβω webhooks που έχασα;
Όχι από τη Meta, καθώς δεν υπάρχει API για ιστορικά δεδομένα webhook. Η εφάπαξ εισαγωγή ιστορικού ενός αριθμού Coexistence εκτελείται μόνο κατά την ένταξη και δεν μπορεί να ζητηθεί ξανά για την ίδια σύνδεση.
Στέλνει η Meta την ίδια ενημέρωση σε περισσότερους από έναν server;
Στέλνει σε κάθε εφαρμογή συνδεδεμένη στον WhatsApp Business Account για αυτό το πεδίο. Με παράκαμψη προορισμού, τα πεδία μηνυμάτων του αριθμού στέλνονται στο URL της παράκαμψης αντί για το προεπιλεγμένο callback της εφαρμογής.
Συνεχίστε την ανάγνωση
Έτοιμοι να ξεκινήσετε;
Ρυθμίστε το WhatsApp Coexistence σε λίγα λεπτά, όχι σε μήνες. Η εφαρμογή συνεχίζει να λειτουργεί στο τηλέφωνο.
Ξεκινήστε δωρεάν δοκιμήΕπαληθεύτηκε στις