[ טוען... ]

Idempotency ב-API: מדריך למניעת כפילויות בניסיונות חוזרים

תאריך: 10.11.2026
זמן קריאה: 20 דקות
לידור כהן
מייסד, לידור דיגיטל

שיתוף:

הירשמו לניוזלטר - תובנות על אוטומציה ו-AI, בלי ספאם

איור של בקשות והודעות כפולות שעוברות דרך שער עם מפתח, כשרק אחת נכנסת לבסיס הנתונים, הממחיש Idempotency ב-API

ניסיון חוזר הוא אחד הכלים הבסיסיים ביותר לאמינות. הרשת נפלה, השרת לא ענה בזמן, ה-webhook לא קיבל 2xx, ולכן שולחים שוב. הבעיה מתחילה כשהבקשה הראשונה דווקא הצליחה ורק התשובה הלכה לאיבוד בדרך. במצב כזה הניסיון החוזר לא מתקן תקלה אלא משכפל תוצאה: הלקוח מחויב פעמיים, אותו ליד נכנס ל-CRM שלוש פעמים, ואותה הודעת וואטסאפ נשלחת שוב ושוב. הפתרון לבעיה נקרא Idempotency ב-API: תכנון שבו חזרה על אותה פעולה משאירה את המערכת באותו מצב כמו ביצוע יחיד.

המאמר Retry storm: איך ניסיונות חוזרים מפילים את הפרודקשן עסק בצד אחד של המטבע: איך ניסיונות חוזרים עלולים להציף שירות, ואיך backoff, ‏jitter ו-circuit breaker מרסנים אותם. המדריך הזה עוסק בצד השני, כלומר במה שקורה לתופעות הלוואי (side effects) כשהניסיון החוזר מגיע ליעדו. גם מערכת עם backoff מושלם תשלח בקשות כפולות. השאלה היא רק אם השרת יודע לזהות אותן.

המדריך מכסה שלוש שכבות: מפתח אידמפוטנטיות לבקשות API, ‏unique constraint ב-Postgres כמנגנון האכיפה, ומניעת כפילויות ב-webhook ובאוטומציות של n8n ו-WhatsApp. לאורך הדרך מופיעות דוגמאות קוד ב-TypeScript וב-SQL שאפשר להתאים לפרויקט קיים.

למה ניסיונות חוזרים מייצרים חיובים כפולים ולידים כפולים

בכל קריאת רשת יש רגע עיוור: השרת כבר ביצע את הפעולה, אבל הלקוח עדיין לא קיבל אישור. אם החיבור נקטע בדיוק שם, או שה-timeout של הלקוח קצר מזמן העיבוד בשרת, הלקוח לא יכול לדעת אם הפעולה התבצעה.

מבחינת הלקוח, האפשרות הסבירה היחידה היא לנסות שוב. בלי הגנה בצד השרת, הפעולה פשוט מתבצעת בפעם השנייה. ניסיונות חוזרים ב-API הם לכן לא באג אלא חלק מהחוזה: כל endpoint שמשנה מצב צריך להניח שיקבל את אותה בקשה יותר מפעם אחת.

שלושה תרחישים מוכרים

  • כפילויות בתשלומים: השרת מחייב כרטיס דרך ספק סליקה, הספק מאשר, אבל התשובה לא חוזרת בזמן. קוד ה-retry שולח את בקשת החיוב שוב, והלקוח רואה שני חיובים בפירוט האשראי.
  • לידים כפולים: טופס באתר שולח webhook לאוטומציה, האוטומציה יוצרת ליד ב-CRM, אבל לוקח לה יותר מדי זמן לענות. השולח מניח שהמשלוח נכשל ושולח שוב, ונציג המכירות מקבל את אותו ליד פעמיים.
  • הודעות וואטסאפ כפולות: בוט מקבל הודעה נכנסת, קורא למודל שפה שמגיב לאט, ובינתיים הפלטפורמה מניחה שה-webhook לא נקלט ושולחת אותו שוב. הלקוח מקבל שתי תשובות זהות, או גרוע מכך, שתי תשובות שונות.
  • פעולות שרשרת: workflow שיוצר הזמנה, שולח חשבונית ומעדכן מלאי. כפילות בשלב הראשון מתגלגלת לכל השלבים שאחריו.

התרחיש של הבוט מתואר היטב אצל AgentMail: כל שכבה במערכת מוסרת הודעות לפחות פעם אחת (at-least-once), ו-webhook שלא מקבל 2xx בתוך 15 שניות נשלח שוב. במילים אחרות, handler איטי, למשל כזה שממתין לקריאת LLM, מייצר את הכפילויות של עצמו.

בשוק הישראלי, שבו חלק גדול מהתקשורת העסקית עובר בוואטסאפ, הודעה כפולה ללקוח או שתי שיחות מאותו נציג על אותו ליד פוגעות באמון באופן מיידי. חיוב כפול כבר מוביל לפניות שירות, לביטולי עסקה ולפעמים להכחשות חיוב מול חברת האשראי.

Idempotent מול Safe: מה תקן HTTP אומר

תקן HTTP מבחין בין שתי תכונות. מתודה safe היא מתודה שלא אמורה לשנות מצב בשרת, כמו GET או HEAD. מתודה idempotent היא מתודה שהשפעתה המיועדת על השרת זהה בין אם נשלחה פעם אחת ובין אם כמה פעמים. לפי RFC 9110, ‏PUT ו-DELETE הן אידמפוטנטיות, וכך גם כל המתודות הבטוחות. ‏POST ו-PATCH אינן מוגדרות כאידמפוטנטיות.

הבעיה היא שרוב הפעולות העסקיות המעניינות, כמו חיוב, יצירת הזמנה או שליחת הודעה, ממומשות כ-POST. כאן נכנס המפתח. Brandur Leach מגדיר endpoint אידמפוטנטי כ-endpoint שאפשר לקרוא לו כל מספר פעמים, עם הבטחה שתופעות הלוואי יתרחשו פעם אחת בלבד.

Aleksei Aleinikov מדגיש נקודה מהותית: אידמפוטנטיות היא תכונה של שכבת האחסון, לא header שמוסיפים לבקשה. ה-header רק מעביר מזהה. האכיפה האמיתית קורית בבסיס הנתונים, וזה בדיוק המקום שבו רוב המימושים נשברים.

מפתח אידמפוטנטיות: מי מייצר, איך שולחים וכמה זמן שומרים

מפתח אידמפוטנטיות הוא מזהה ייחודי שהלקוח מייצר ומצרף לבקשה, והשרת שומר אותו כדי לעקוב אחרי מצב הבקשה (Brandur). לפי אותו מקור, השם עצמו הגיע מה-API של Stripe, והדרך המקובלת להעביר אותו היא header בשם Idempotency-Key עם ערך UUID:

POST /v1/charges HTTP/1.1
Content-Type: application/json
Idempotency-Key: 0ccb7813-e63d-4377-93c5-476cb93038f3

{ "orderId": "ord_1042", "amount": 34900, "currency": "ils" }

הכלל החשוב ביותר: מייצרים פעם אחת

הטעות הנפוצה ביותר היא לייצר את המפתח בתוך לולאת ה-retry. לפי clixo.sh, קריאה ל-uuid() בתוך הלולאה נותנת אפס הגנה, כי כל ניסיון נראה לשרת כמו בקשה חדשה לגמרי. הדרך הנכונה היא לייצר את המפתח פעם אחת, לשמור אותו לפני הקריאה ל-API, ולהשתמש בו שוב בכל ניסיון חוזר.

גם Zuplo ממליצים שהלקוח ייצר את המפתח (למשל UUIDv4) לפני הבקשה הראשונה, ולא במהלך הניסיונות החוזרים. ההבדל בקוד קטן, אבל ההבדל בהתנהגות דרמטי:

// שגוי: מפתח חדש בכל ניסיון, השרת רואה שלוש בקשות שונות
for (let attempt = 1; attempt <= 3; attempt++) {
  await chargeCard(order, { idempotencyKey: crypto.randomUUID() });
}

// נכון: מפתח אחד, נשמר עם ההזמנה לפני הקריאה הראשונה
const key = order.paymentIdempotencyKey ?? `order_${order.id}_payment`;
await db.orders.update(order.id, { paymentIdempotencyKey: key });

for (let attempt = 1; attempt <= 3; attempt++) {
  try {
    return await chargeCard(order, { idempotencyKey: key });
  } catch (err) {
    if (!isRetryable(err) || attempt === 3) throw err;
    await sleep(backoffWithJitter(attempt));
  }
}

שמירת המפתח ברשומת ההזמנה לפני הקריאה חשובה במיוחד כשהתהליך עצמו עלול לקרוס. אם השרת נופל באמצע ומופעל מחדש, הוא ימצא את המפתח בבסיס הנתונים וישתמש בו, במקום לייצר חדש ולחייב שוב.

מה לא לשמש כמפתח

אותו מקור מזהיר שכתובת אימייל או חותמת זמן הם מפתחות גרועים. אימייל אינו ייחודי לפעולה, כי אותו לקוח יכול לבצע שתי הזמנות לגיטימיות. חותמת זמן משתנה בין ניסיונות, או לחלופין מתנגשת בין שני לקוחות שונים באותו רגע.

מפתח טוב נגזר מהפעולה העסקית עצמה (מזהה הזמנה, מזהה אירוע) או נוצר אקראית פעם אחת ונשמר לצידה. דוגמה שמופיעה ב-clixo.sh היא order_${orderId}_payment.

נקודה רלוונטית במיוחד למערכות בעברית: מפתחות צריכים להיגזר ממזהים, לא מתוכן ההודעה. טקסט בעברית עלול להכיל תווי כיווניות בלתי נראים (כמו U+200F, ה-RIGHT-TO-LEFT MARK) או צורות נרמול Unicode שונות, כך ששתי מחרוזות שנראות זהות על המסך יפיקו hash שונה. מנגד, שתי הודעות זהות בתוכן (למשל לקוח שכותב פעמיים תודה) הן אירועים שונים לגיטימיים. מפתח שמבוסס על מזהה חסין לשתי הבעיות.

כמה זמן שומרים מפתח

מפתחות נועדו לנכונות בטווח הקצר, לא לארכיון קבוע של בקשות. Brandur ממליץ למחזר מפתחות אחרי אופק של כ-24 שעות, ו-Zuplo מציעים תפוגה דומה. לפי הסיכום של clixo.sh לתיעוד של Stripe, ב-API v1 מפתחות עשויים להימחק כשהם בני 24 שעות לפחות.

עוד פרט מאותו מקור: ב-Stripe המפתחות חלים על בקשות POST ואין להם השפעה על GET או DELETE, שאמורות להיות אידמפוטנטיות מטבען.

Idempotency ב-API עם Postgres ו-TypeScript

לפני שכותבים קוד, כדאי להבין את ההבחנה ש-Brandur עושה בין שני מקרים. אם ה-endpoint משנה רק מצב מקומי בבסיס נתונים ACID, הכי פשוט למפות כל בקשה לטרנזקציה אחת. מפתחות עם נקודות התאוששות (recovery points) ושלבים אטומיים נדרשים רק כשצריך לשנות מצב חיצוני באופן סינכרוני, למשל חיוב ב-Stripe.

העיקרון למקרה המקומי מנוסח בקצרה אצל Peter Kraft: רושמים את מפתח האידמפוטנטיות בטבלת רישום באותה טרנזקציה של הפעולה עצמה, כך ששתיהן נשמרות יחד או ששתיהן לא נשמרות כלל.

סכמת הטבלה

CREATE TABLE idempotency_keys (
  account_id     bigint       NOT NULL,
  idem_key       text         NOT NULL,
  request_path   text         NOT NULL,
  request_hash   text         NOT NULL,
  status         text         NOT NULL DEFAULT 'started'
                 CHECK (status IN ('started', 'completed')),
  response_code  integer,
  response_body  jsonb,
  locked_at      timestamptz  NOT NULL DEFAULT now(),
  created_at     timestamptz  NOT NULL DEFAULT now(),
  PRIMARY KEY (account_id, idem_key)
);

CREATE INDEX idempotency_keys_created_at_idx
  ON idempotency_keys (created_at);

כמה החלטות תכנון שכדאי לשים לב אליהן:

  • מפתח ראשי מורכב: ה-PRIMARY KEY הוא צירוף של חשבון ומפתח. כך שני לקוחות שונים שבמקרה שולחים אותו ערך לא מתנגשים. פוסט ב-LinkedIn ממליץ בדיוק על תיחום כזה של המפתח.
  • request_hash: טביעת אצבע של גוף הבקשה, שמאפשרת לזהות שימוש חוזר במפתח עם פרמטרים אחרים.
  • response_code ו-response_body: התגובה המקורית נשמרת כדי להחזיר אותה כמו שהיא לכל ניסיון חוזר.
  • status ו-locked_at: מאפשרים לזהות בקשה שעדיין בתהליך, ובקשה שנתקעה באמצע.
  • אינדקס על created_at: משרת את עבודת הניקוי התקופתית.

ה-unique constraint ב-Postgres (כאן בצורת PRIMARY KEY) הוא לב המנגנון. קוד אפליקציה יכול לטעות, לרוץ במקביל בעשרה pods או להיתקע באמצע. האילוץ בבסיס הנתונים לא מתפשר.

מקרה פשוט: יצירת ליד בטרנזקציה אחת

הדוגמה הבאה משתמשת בספריית pg ומממשת endpoint שיוצר ליד. כל העבודה קורית בטרנזקציה אחת:

import { Pool } from 'pg';
import { createHash } from 'node:crypto';

const pool = new Pool({ connectionString: process.env.DATABASE_URL });

type StoredResponse = { status: number; body: unknown };

export function hashRequest(path: string, body: unknown): string {
  // בפרודקשן עדיף JSON קנוני (מפתחות ממוינים) כדי שסדר שדות לא ישנה את ה-hash
  return createHash('sha256').update(path + JSON.stringify(body)).digest('hex');
}

export async function createLead(
  accountId: number,
  idemKey: string,
  input: { name: string; phone: string; source: string }
): Promise<StoredResponse> {
  const reqHash = hashRequest('/leads', input);
  const client = await pool.connect();
  try {
    await client.query('BEGIN');

    const claim = await client.query(
      `INSERT INTO idempotency_keys (account_id, idem_key, request_path, request_hash)
       VALUES ($1, $2, '/leads', $3)
       ON CONFLICT (account_id, idem_key) DO NOTHING
       RETURNING idem_key`,
      [accountId, idemKey, reqHash]
    );

    if (claim.rowCount === 0) {
      await client.query('ROLLBACK');
      return replayExisting(accountId, idemKey, reqHash);
    }

    const lead = await client.query(
      `INSERT INTO leads (account_id, name, phone, source)
       VALUES ($1, $2, $3, $4) RETURNING id`,
      [accountId, input.name, input.phone, input.source]
    );

    const response: StoredResponse = { status: 201, body: { leadId: lead.rows[0].id } };

    await client.query(
      `UPDATE idempotency_keys
          SET status = 'completed', response_code = $3, response_body = $4
        WHERE account_id = $1 AND idem_key = $2`,
      [accountId, idemKey, response.status, JSON.stringify(response.body)]
    );

    await client.query('COMMIT');
    return response;
  } catch (err) {
    await client.query('ROLLBACK');
    throw err;
  } finally {
    client.release();
  }
}

אם משהו נכשל באמצע, למשל הכנסת הליד נכשלת בגלל ולידציה, ה-ROLLBACK מוחק גם את שורת המפתח. הלקוח יכול לנסות שוב עם אותו מפתח, והבקשה תרוץ מההתחלה. זה בדיוק היתרון של מפתח ופעולה שנשמרים יחד.

ה-route עצמו נשאר דק:

app.post('/leads', async (req, res) => {
  const key = req.header('Idempotency-Key');
  if (!key || key.length > 255) {
    return res.status(400).json({ error: 'missing_idempotency_key' });
  }
  const result = await createLead(req.user.accountId, key, req.body);
  res.status(result.status).json(result.body);
});

מרוץ תהליכים: שתי בקשות עם אותו מפתח באותו רגע

לפי Aleinikov, מרוץ תהליכים (race condition) הוא מה ששובר את רוב המימושים, ו-Zuplo מונים טיפול בבקשות מקבילות כאחד השיקולים המרכזיים.

המימוש הנאיבי נראה כך: SELECT כדי לבדוק אם המפתח קיים, ואם לא, מבצעים את הפעולה ואז INSERT. כששתי בקשות מגיעות באותה מילישנייה (קורה יותר משנדמה, למשל לחיצה כפולה על כפתור או לקוח עם timeout אגרסיבי), שתיהן עוברות את ה-SELECT, שתיהן לא מוצאות את המפתח, ושתיהן מבצעות את הפעולה.

הגישה בקוד שלמעלה עוקפת את הבעיה כי היא לא בודקת ואז כותבת, אלא כותבת ישר ונותנת לאילוץ להחליט. כך זה מתנהג ב-Postgres ברמת הבידוד ברירת המחדל (READ COMMITTED):

  1. בקשה א' מבצעת INSERT למפתח, והשורה עדיין לא committed.
  2. בקשה ב' מבצעת INSERT לאותו מפתח. האינדקס הייחודי מזהה שורה מתנגשת שטרם הוכרעה, ובקשה ב' ממתינה.
  3. אם בקשה א' מבצעת COMMIT, בקשה ב' מקבלת התנגשות, ה-DO NOTHING מחזיר אפס שורות, והיא עוברת למסלול ה-replay ורואה את התגובה השמורה.
  4. אם בקשה א' מבצעת ROLLBACK, בקשה ב' מצליחה להכניס את השורה ומבצעת את הפעולה בעצמה.

בשני המקרים הפעולה מתבצעת בדיוק פעם אחת. ברמות בידוד גבוהות יותר (REPEATABLE READ או SERIALIZABLE) בקשה ב' עשויה לקבל שגיאת serialization במקום, ולכן הקוד צריך לתפוס את השגיאה ולנסות שוב.

פעולות חיצוניות: חיוב, הודעה וקריאה לצד שלישי

אי אפשר לעשות ROLLBACK להודעת וואטסאפ שכבר יצאה או לחיוב שכבר אושר. גם לא כדאי להחזיק טרנזקציה פתוחה בזמן קריאת רשת שעלולה להימשך שניות. לכן, לפי Brandur, פעולות שמשנות מצב חיצוני מחולקות לשלבים אטומיים:

export async function chargeOrder(accountId: number, idemKey: string, orderId: string) {
  const reqHash = hashRequest('/charges', { orderId });

  // שלב 1: תפיסת המפתח בטרנזקציה קצרה שנסגרת מיד
  const claim = await pool.query(
    `INSERT INTO idempotency_keys (account_id, idem_key, request_path, request_hash)
     VALUES ($1, $2, '/charges', $3)
     ON CONFLICT (account_id, idem_key) DO NOTHING
     RETURNING idem_key`,
    [accountId, idemKey, reqHash]
  );
  if (claim.rowCount === 0) return replayExisting(accountId, idemKey, reqHash);

  // שלב 2: הקריאה החיצונית, עם מפתח יציב שמועבר גם לספק
  const charge = await paymentProvider.charge({
    orderId,
    idempotencyKey: `${accountId}_${idemKey}`,
  });

  // שלב 3: שמירת התוצאה ועדכון ההזמנה באותה טרנזקציה
  const response = { status: 201, body: { chargeId: charge.id } };
  const client = await pool.connect();
  try {
    await client.query('BEGIN');
    await client.query(
      `UPDATE orders SET paid = true, charge_id = $2 WHERE id = $1`,
      [orderId, charge.id]
    );
    await client.query(
      `UPDATE idempotency_keys
          SET status = 'completed', response_code = $3, response_body = $4
        WHERE account_id = $1 AND idem_key = $2`,
      [accountId, idemKey, response.status, JSON.stringify(response.body)]
    );
    await client.query('COMMIT');
  } catch (err) {
    await client.query('ROLLBACK');
    throw err;
  } finally {
    client.release();
  }
  return response;
}

הנקודה הקריטית היא שלב 2. אם השרת קורס אחרי שהספק אישר את החיוב אבל לפני שלב 3, השורה נשארת במצב started. בקשה מקבילה שמגיעה בזמן הזה מקבלת 409 (בקשה בתהליך). כשה-locked_at ישן מספיק, תהליך התאוששות יכול להמשיך את הבקשה, ומכיוון שהוא שולח לספק את אותו מפתח, ספק שתומך באידמפוטנטיות (כמו Stripe) יחזיר את אותו חיוב במקום ליצור חדש.

זו בדיוק הסיבה שהמפתח מועבר גם downstream. בלי זה, שלב ההתאוששות היה צריך לנחש אם החיוב בוצע. במימוש המלא של Brandur מופיעים גם jobs ברקע ו-reaper שמנקה מפתחות שנתקעו, וזו המורכבות שמשלמים עליה כשנוגעים במערכות חיצוניות.

לגבי ספקי סליקה ישראליים: התדריכים הזמינים לא מכסים את התנהגות ה-retry והאידמפוטנטיות שלהם, ולכן כדאי לבדוק בתיעוד של כל ספק אם קיים פרמטר מקביל ל-Idempotency-Key. אם אין, שלב ההתאוששות צריך לשאול את הספק על סטטוס העסקה לפי מזהה ההזמנה לפני חיוב חוזר.

שמירת התגובה ואימות הפרמטרים

שני עקרונות נוספים מופיעים כמעט בכל מקור. הראשון: שומרים את התגובה, לא רק את המפתח. לפי Zuplo, השרת שומר את קוד הסטטוס ואת גוף התגובה בין אם הפעולה הצליחה ובין אם נכשלה, ומחזיר אותם לכל כפילות. לפי clixo.sh, גם Stripe שומר את התגובה מרגע שהביצוע התחיל, כולל שגיאות שרת, ומחזיר אותה לניסיונות חוזרים תואמים.

השני: מוודאים שהבקשה החוזרת זהה למקורית. Stripe דוחה ניסיון חוזר שמשתמש במפתח קיים עם פרמטרים שונים (clixo.sh), ו-Zuplo ממליצים על אותה בדיקה. כך נראית פונקציית ה-replay:

async function replayExisting(
  accountId: number,
  idemKey: string,
  reqHash: string
): Promise<StoredResponse> {
  const { rows } = await pool.query(
    `SELECT request_hash, status, response_code, response_body
       FROM idempotency_keys
      WHERE account_id = $1 AND idem_key = $2`,
    [accountId, idemKey]
  );
  const row = rows[0];

  if (!row) {
    // השורה נמחקה בינתיים (למשל בניקוי תקופתי)
    return { status: 409, body: { error: 'retry_later' } };
  }
  if (row.request_hash !== reqHash) {
    return { status: 422, body: { error: 'idempotency_key_reused_with_different_params' } };
  }
  if (row.status === 'completed') {
    return { status: row.response_code, body: row.response_body };
  }
  return { status: 409, body: { error: 'request_in_progress' } };
}

המלצה מעשית: שגיאות שקרו לפני שבוצעה תופעת לוואי כלשהי (למשל כשל ולידציה או בסיס נתונים שלא זמין) עדיף לא לשמור, כך שניסיון חוזר יוכל לרוץ מחדש. שגיאות סופיות שקרו אחרי שהתחילה פעולה חיצונית, כמו סירוב של חברת האשראי, צריך לשמור כדי שהלקוח יקבל את אותה תשובה בכל פעם.

השוואה בין הגישות

גישה

מתי מתאימה

יתרונות

חסרונות

מפתח באותה טרנזקציה מקומית

רק מצב מקומי משתנה (יצירת ליד, עדכון רשומה)

הכי פשוטה ועמידה, המפתח והפעולה נשמרים אטומית

לא מכסה חיובים או שליחת הודעות

מפתח בסגנון Stripe עם תגובה שמורה ונקודות התאוששות

שינוי מצב חיצוני (סליקה, הודעות, API של צד שלישי)

מאפשרת ללקוח לנסות שוב בבטחה עד לתשובה סופית

מורכבת: שלבים אטומיים, jobs ברקע, ניקוי ומרוצים

טבלת processed_events עם מזהה אירוע ייחודי

webhooks נכנסים

מכסה כפילויות שמפתחות API לא מכסים, אילוץ פשוט

חובה לרשום לפני פעולה ולענות בזמן, ומזהה שגוי מכניס כפילויות

הטבלה מבוססת על ההשוואה אצל Brandur ועל הדפוס שמתואר ב-clixo.sh.

מניעת כפילויות ב-webhook: רישום לפני פעולה ותגובה מהירה

טעות נפוצה היא להניח שמפתחות אידמפוטנטיות פותרים גם את הצד הנכנס. לפי clixo.sh, מפתחות של Stripe מגנים רק על הקריאות שהשרת שולח ל-Stripe. משלוחים כפולים של webhooks דורשים מנגנון נפרד בבסיס הנתונים של המקבל, בדרך כלל טבלת processed_events עם unique constraint על מזהה האירוע.

המתכון של AgentMail לסוכנים שמגיבים להודעות נכנסות מתמצת את העיקרון בשלושה צעדים:

  1. מבצעים dedupe לפי מזהה אירוע יציב.
  2. רושמים את האירוע לפני שפועלים.
  3. נותנים מפתח גם לפעולה היוצאת (למשל שליחת התשובה), כדי שתתבצע פעם אחת גם אחרי קריסה או השבתה.

בחירת המזהה הנכון

לא כל מזהה מתאים. לפי AgentMail, צריך לבחור מזהה שנשאר יציב לאורך סוג החזרה שממנו מתגוננים. ‏message_id לבדו עלול למזג עבודה בין תיבות דואר שונות, ולכן הם מצמידים inbox_id ל-message_id. עוד מהמקור: header ה-Message-ID מוגדר ב-RFC 5322 רק כ-SHOULD, כלומר אי אפשר לסמוך שתמיד יופיע.

הלקח הכללי: המזהה צריך להיות מזהה האירוע שהספק מקצה (event ID), מתוחם לפי מקור או חשבון, ולא נגזר מתוכן ה-payload. אם אותו endpoint מקבל אירועים מכמה מספרי וואטסאפ או מכמה חשבונות סליקה, יש להוסיף את מזהה המקור למפתח.

סכמה ו-handler

CREATE TABLE inbound_events (
  source        text         NOT NULL,
  event_id      text         NOT NULL,
  payload       jsonb        NOT NULL,
  status        text         NOT NULL DEFAULT 'received',
  received_at   timestamptz  NOT NULL DEFAULT now(),
  processed_at  timestamptz,
  PRIMARY KEY (source, event_id)
);
app.post('/webhooks/payments', async (req, res) => {
  // 1. אימות חתימה לפי תיעוד הספק, לפני כל דבר אחר
  if (!verifySignature(req)) return res.sendStatus(401);

  const event = req.body as { id: string; type: string };

  // 2. רישום לפני פעולה. כפילות פשוט לא נכנסת
  const { rowCount } = await pool.query(
    `INSERT INTO inbound_events (source, event_id, payload)
     VALUES ('payments', $1, $2)
     ON CONFLICT (source, event_id) DO NOTHING`,
    [event.id, JSON.stringify(event)]
  );

  // 3. תגובה מהירה, גם לכפילויות, אחרת השולח ימשיך לנסות
  res.sendStatus(200);

  if (rowCount === 1) queue.notify('inbound_events');
});

שימו לב שגם כפילות מקבלת 200. החזרת שגיאה על אירוע שכבר עובד רק תגרום לשולח לנסות שוב ושוב.

למה רושמים ולא מעבדים מיד

חלון ה-15 שניות של AgentMail הוא ספציפי לספק הזה, ולספקים אחרים יש חלונות שונים. העיקרון זהה: handler שמחכה ל-LLM, ל-CRM איטי או לשירות חיצוני מסתכן בחריגה מהחלון וביצירת הכפילויות של עצמו. לכן ה-handler רק רושם ועונה, ו-worker נפרד מבצע את העבודה:

async function processNextEvent(): Promise<void> {
  const client = await pool.connect();
  try {
    await client.query('BEGIN');
    const { rows } = await client.query(
      `SELECT source, event_id, payload
         FROM inbound_events
        WHERE status = 'received'
        ORDER BY received_at
        LIMIT 1
        FOR UPDATE SKIP LOCKED`
    );
    if (rows.length === 0) {
      await client.query('COMMIT');
      return;
    }
    const ev = rows[0];
    await handleBusinessLogic(client, ev.payload);
    await client.query(
      `UPDATE inbound_events
          SET status = 'processed', processed_at = now()
        WHERE source = $1 AND event_id = $2`,
      [ev.source, ev.event_id]
    );
    await client.query('COMMIT');
  } catch (err) {
    await client.query('ROLLBACK');
    throw err;
  } finally {
    client.release();
  }
}

עמודת status פותרת בעיה עדינה בעיקרון של רישום לפני פעולה. אם רושמים את האירוע ואז ה-worker קורס, האירוע לא אובד, כי הוא נשאר במצב received ויטופל בסבב הבא. ‏FOR UPDATE SKIP LOCKED מאפשר להריץ כמה workers במקביל בלי שיתפסו את אותו אירוע.

אם handleBusinessLogic שולח הודעה או קורא ל-API חיצוני, ה-ROLLBACK לא יבטל את מה שכבר יצא. לכן הפעולה היוצאת צריכה מפתח משלה, כפי שמתואר בסעיף הבא. וכשה-worker קורא לשירותים חיצוניים, כדאי להגדיר לו timeout מפורש. המדריך Node.js fetch timeout: מדריך הקשחה ל-fetch בפרודקשן מפרט איך עושים את זה נכון.

אידמפוטנטיות ב-n8n ובאוטומציות וואטסאפ

המקורות שעליהם מבוסס המדריך לא עוסקים ב-n8n או ב-WhatsApp Business API באופן ספציפי. הסעיף הזה מיישם את אותם עקרונות על הכלים האלה, ולכן כדאי לאמת את הפרטים מול התיעוד העדכני של n8n ושל Meta לפני הטמעה.

Webhook נכנס ב-n8n

אידמפוטנטיות ב-n8n נשענת על אותם שלושה צעדים: לענות מהר, לרשום לפני פעולה ולסנן כפילויות לפי מזהה יציב. מבנה workflow מומלץ:

  1. Webhook node שמוגדר לענות מיד (אפשרות Respond: Immediately), כדי שהשולח יקבל 200 גם אם שאר ה-workflow ייקח זמן.
  2. Postgres node במצב Execute Query, שמבצע INSERT עם ON CONFLICT DO NOTHING ומחזיר שורה רק כשהאירוע חדש.
  3. המשך ה-workflow (קריאה ל-LLM, יצירת ליד, שליחת תשובה) רץ רק כשהתקבלה שורה.
INSERT INTO processed_events (source, event_id)
VALUES ('whatsapp', $1)
ON CONFLICT (source, event_id) DO NOTHING
RETURNING event_id;

את $1 מעבירים דרך אפשרות Query Parameters של ה-node, למשל עם ביטוי שמחלץ את מזהה ההודעה מה-payload, ולא בהדבקת מחרוזת לתוך ה-SQL. הדבקה ישירה פותחת פתח ל-SQL injection, כי ה-payload מגיע מבחוץ.

כשאין כפילות, השאילתה מחזירה שורה אחת וה-workflow ממשיך. כשיש כפילות, היא מחזירה אפס שורות, ובהגדרות ברירת המחדל n8n לא מריץ את ה-nodes הבאים כשאין להם items. אם הופעלה בהגדרות ה-node האפשרות Always Output Data, צריך להוסיף IF node שבודק במפורש אם הוחזר event_id. ב-n8n קיים גם node בשם Remove Duplicates, אבל טבלה ב-Postgres עם אילוץ ייחודי נותנת שליטה מלאה על התיחום, על התפוגה ועל הבדיקות.

נקודה חשובה: workflow שמסנן כפילויות נראה מבחוץ בדיוק כמו workflow שהפסיק לעבוד, כי שניהם לא עושים כלום. כדאי לשלב ניטור כמו זה שמתואר ב-ניטור n8n: איך לזהות workflow שהפסיק לרוץ בשקט, ולספור בנפרד אירועים חדשים ואירועים כפולים.

WhatsApp: מזהה ההודעה הנכנסת וסינון סטטוסים

ב-WhatsApp Cloud API כל הודעה נכנסת מגיעה עם מזהה הודעה ייחודי (המתחיל בדרך כלל ב-wamid), וזה המזהה הטבעי ל-dedupe. בנוסף, אותו endpoint מקבל גם webhooks על סטטוסים של הודעות יוצאות (נשלחה, נמסרה, נקראה). כדאי לסנן אותם בשלב מוקדם, אחרת webhook של סטטוס עלול להפעיל את הבוט כאילו הגיעה הודעה חדשה.

כמו בכל webhook, יש לאמת את החתימה ש-Meta שולחת (header בשם X-Hub-Signature-256) לפני שמכניסים משהו לבסיס הנתונים, ולתחום את המפתח לפי מספר הטלפון העסקי אם אותו endpoint משרת כמה מספרים.

הודעה יוצאת: טבלת outbox עם מפתח

הצעד השלישי במתכון של AgentMail, מפתח לפעולה היוצאת, הוא החשוב ביותר בבוט וואטסאפ. ככל הידוע, ל-Cloud API אין מנגנון Idempotency-Key מתועד כמו של Stripe, ולכן ההגנה צריכה להיות בצד שלכם:

CREATE TABLE outbound_messages (
  dedupe_key   text PRIMARY KEY,               -- למשל reply:<wamid של ההודעה הנכנסת>
  to_phone     text NOT NULL,
  body         text NOT NULL,
  status       text NOT NULL DEFAULT 'pending', -- pending | sending | sent
  provider_id  text,
  updated_at   timestamptz NOT NULL DEFAULT now()
);

-- תפיסת ההודעה לפני שליחה: רק תהליך אחד יקבל שורה
UPDATE outbound_messages
   SET status = 'sending', updated_at = now()
 WHERE dedupe_key = $1 AND status = 'pending'
RETURNING to_phone, body;

הזרימה: יוצרים שורה עם INSERT ... ON CONFLICT DO NOTHING לפי מפתח שנגזר מההודעה הנכנסת, תופסים אותה עם ה-UPDATE שלמעלה, שולחים, ושומרים את מזהה ההודעה שהוחזר תוך מעבר ל-sent. גם אם ה-webhook הנכנס יעובד פעמיים, רק תהליך אחד יצליח לתפוס את השורה.

חשוב להבין את הגבול: בלי תמיכה של הספק, exactly-once מושלם לא אפשרי. אם התהליך קורס אחרי השליחה ולפני העדכון ל-sent, השורה תישאר ב-sending. כאן צריך להחליט: לשלוח שוב (סיכון להודעה כפולה) או לסמן לבדיקה ידנית (סיכון להודעה שלא נשלחה). לתשובות בוט שגרתיות, בדיקה ידנית או דילוג הם בדרך כלל ברירה סבירה יותר. להודעות קריטיות כמו קוד אימות, שליחה חוזרת עדיפה. העיקר שזו תהיה החלטה מודעת ולא תוצאה מקרית.

לידים ב-CRM: כפילות בקשה מול כפילות ישות

באוטומציות לידים יש שני סוגי כפילויות שקל לבלבל ביניהם:

  • כפילות בקשה: אותו משלוח טופס הגיע פעמיים בגלל retry. כאן המפתח הוא מזהה ההגשה שהטופס או הפלטפורמה מייצרים, וזה תפקידה של האידמפוטנטיות.
  • כפילות ישות: אותו אדם מילא את הטופס פעמיים בהפרש של שבוע. זו לא כפילות טכנית אלא החלטה עסקית: לעדכן ליד קיים, ליצור חדש או לקשר ביניהם.

לסוג השני מתאים upsert לפי מספר טלפון מנורמל. בישראל משמעות הדבר היא להמיר פורמטים כמו 050-1234567 לפורמט בינלאומי אחיד (+972501234567) לפני ההשוואה, אחרת אותו לקוח יופיע כשני אנשים. אבל אסור להשתמש במספר הטלפון או באימייל כמפתח האידמפוטנטיות עצמו, מאותה סיבה ש-clixo.sh פוסל אימייל: הוא מזהה אדם, לא פעולה. הרחבה על חיבור טפסים ואוטומציות למערכות CRM אפשר למצוא ב-איך לחבר את ה-CRM שלכם לאוטומציה.

תפוגה, reconciliation וצ'קליסט בדיקות

מפתחות שלא נמחקים הופכים לטבלה שגדלה בלי סוף. עבודת ניקוי פשוטה, למשל job מתוזמן או pg_cron, מספיקה:

DELETE FROM idempotency_keys
 WHERE created_at < now() - interval '24 hours'
   AND status = 'completed';

מפתחות שנשארו במצב started אחרי זמן רב לא נמחקים אוטומטית אלא עוברים לבדיקה, כי הם בדיוק המקרים שבהם לא ברור אם הפעולה החיצונית בוצעה.

לטבלת האירועים הנכנסים כדאי לקבוע תפוגה לפי מדיניות ה-retry של כל ספק. חלק מהספקים ממשיכים לנסות לשלוח webhook במשך פרק זמן ארוך, ולכן חלון השמירה צריך להיות לפחות כמו חלון הניסיונות החוזרים של הספק.

מה עושים אחרי שהמפתח פג

כאן מסתתרת מלכודת. לפי clixo.sh, אחרי שחלון השמירה עבר צריך לבדוק את התוצאה של הפעולה המקורית (reconcile) לפני שמנסים שוב. יצירת מפתח חדש כל יום, למשל במשימת לילה שמנסה שוב חיובים שנכשלו, עלולה ליצור בדיוק את הכפילויות שהמנגנון נועד למנוע. ‏Brandur מנסח זאת כך: המפתחות נועדו לנכונות בטווח הקרוב, לא לארכיון קבוע.

בפועל, תהליך retry שרץ אחרי יותר מ-24 שעות צריך קודם לשאול את הספק אם קיימת עסקה עבור מזהה ההזמנה, ורק אם אין, לבצע ניסיון חדש.

צ'קליסט בדיקות

  • שתי בקשות זהות ברצף: השנייה מחזירה את אותו סטטוס ואותו גוף, ונוצרה רשומה אחת בלבד.
  • שתי בקשות זהות במקביל: מריצים עשרות בקשות באותו מפתח במקביל (למשל עם Promise.all) ובודקים שהפעולה התבצעה פעם אחת.
  • אותו מפתח, גוף שונה: מתקבלת שגיאת 422 ולא ביצוע שקט.
  • קריסה באמצע: עוצרים את התהליך אחרי הקריאה החיצונית ולפני שלב 3, ומוודאים שההתאוששות לא מבצעת את הפעולה פעם שנייה.
  • webhook כפול: שולחים את אותו payload פעמיים ובודקים שמתקבל 200 בשתיהן ושהעיבוד קרה פעם אחת.
  • webhook איטי: מדמים עיבוד שלוקח יותר מחלון ה-timeout של השולח, ומוודאים שה-handler עונה מיד.
  • סטטוסים של וואטסאפ: webhook של סטטוס הודעה לא מפעיל את הבוט.
  • מפתח שפג: ניסיון חוזר אחרי הניקוי עובר דרך בדיקת reconciliation ולא דרך ביצוע עיוור.
  • ניטור: יש מדד לכמות הכפילויות שנחסמו. עלייה חדה בו היא סימן מוקדם לבעיית timeout או ל-retry storm.

שאלות נפוצות

האם מפתחות אידמפוטנטיות של Stripe מגנים על ה-webhook handler?

לא. לפי clixo.sh, הם מונעים רק קריאות כפולות מהשרת אל Stripe. לאירועים נכנסים צריך מנגנון נפרד, למשל טבלת processed_events עם unique constraint על מזהה האירוע.

מתי צריך לייצר את מפתח האידמפוטנטיות?

פעם אחת, לפני הניסיון הראשון. שומרים אותו יחד עם רשומת הפעולה ומשתמשים בו שוב בכל ניסיון חוזר. מפתח אקראי חדש בכל ניסיון לא נותן שום הגנה (clixo.sh, Zuplo).

כמה זמן צריך לשמור מפתחות?

המקורות מציעים בערך 24 שעות (Brandur). אחרי החלון הזה לא מייצרים מפתח חדש באופן עיוור, אלא בודקים קודם מה קרה לפעולה המקורית.

מה שומרים יחד עם המפתח?

את התגובה המלאה, כלומר קוד סטטוס וגוף, ולא רק את המפתח. לפי Zuplo שומרים גם תוצאות כושלות, כדי שכל ניסיון חוזר יקבל את אותה תשובה. כדאי גם לשמור hash של הבקשה כדי לזהות שימוש חוזר במפתח עם פרמטרים אחרים.

למה webhooks מגיעים פעמיים?

כי המשלוח מבוסס at-least-once. שולחים מנסים שוב כשלא מתקבל 2xx בתוך חלון הזמן שלהם (15 שניות במקרה של AgentMail), ולכן handler איטי מייצר את הכפילויות של עצמו.

האם בסיס הנתונים לבדו יכול להפוך פעולה לאידמפוטנטית?

כן, כשהפעולה משנה רק מצב מקומי. מכניסים את המפתח לטבלת רישום באותה טרנזקציה של הפעולה, כך ששתיהן נשמרות או ששתיהן לא נשמרות (Peter Kraft). כשמעורבת מערכת חיצונית, צריך גם שלבים אטומיים ומפתח שמועבר לספק.

סיכום

ניסיונות חוזרים הם הכרח, אבל בלי Idempotency ב-API הם הופכים כל תקלת רשת לחיוב כפול, לליד כפול או להודעה כפולה. הפתרון נשען על שלושה רכיבים: מפתח אידמפוטנטיות שהלקוח מייצר פעם אחת ושומר, unique constraint ב-Postgres שאוכף ייחודיות גם תחת מקביליות, ומניעת כפילויות ב-webhook לפי מזהה אירוע יציב, עם רישום לפני פעולה ותגובה מהירה.

לפעולות מקומיות מספיקה טרנזקציה אחת שכוללת את המפתח. לפעולות חיצוניות כמו סליקה ושליחת הודעות נדרשים שלבים אטומיים, שמירת תגובה, אימות פרמטרים ומפתח שמועבר הלאה לספק. באוטומציות n8n ו-WhatsApp אותם עקרונות מתורגמים ל-Webhook שעונה מיד, לשאילתת ON CONFLICT ולטבלת outbox להודעות יוצאות.

לבסוף, כדאי לזכור שהמנגנון לא נגמר בקוד. צריך ניקוי מפתחות, תהליך reconciliation אחרי שהחלון פג, ובדיקות שמדמות במכוון בקשות מקבילות, קריסות ו-webhooks כפולים. יחד עם backoff ו-jitter שמונעים retry storm, המנגנונים האלה הופכים ניסיון חוזר מסיכון לכלי בטוח.

מקורות

וואטסאפ