[ טוען... ]

nginx webhook ולידציה: דחיית payload פגום עם json_set ב-1.31.5

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

שיתוף:

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

איור של שער ב-reverse proxy שמסנן חבילות JSON פגומות של webhook לפני שהן מגיעות לשרת האוטומציות

במשך שנים nginx עבד לפי סדר קבוע: קורא את שורת הבקשה ואת הכותרות, בוחר location לפי ה-URI, ורק אחר כך מזרים את גוף הבקשה ל-upstream. המשמעות עבור webhooks פשוטה: כל payload, תקין או זבל, עובר עד ל-n8n או לשרת ה-Node, ושם מתחילים לבזבז עליו CPU, חיבורים ושורות לוג. nginx webhook ולידציה, כלומר בדיקה בסיסית של תוכן ה-JSON כבר בשכבת ה-reverse proxy, הייתה עד עכשיו עניין של מודולים חיצוניים או סקריפטים.

גרסת ה-mainline ‏nginx 1.31.5 משנה את התמונה. היא מוסיפה לליבת הקוד הפתוח פענוח JSON נייטיב, קריאה מוקדמת של גוף הבקשה ו-locations שמבוססים על משתנים. השילוב הזה מאפשר לחלץ ערך מתוך ה-payload, להחליט לפיו, ולהחזיר 400 עוד לפני שהבקשה נוגעת באפליקציה.

המדריך הזה מסביר מה בדיוק שוחרר, איך json_set ו-client_body_early_read עובדים יחד, מה ידוע (ומה לא) על שיפורי הביצועים, איפה הגישה הזאת נעצרת, ואיך פורסים אותה בהדרגה מול n8n או backend של Node בלי לאבד אירועים אמיתיים. חשוב להבהיר מראש: המודול חדש, והתחביר המדויק שלו צריך להיבדק מול התיעוד הרשמי ומול build אמיתי לפני כל שימוש בפרודקשן.

מה בדיוק שוחרר ב-nginx 1.31.5

לפי הבלוג הרשמי של NGINX, גרסה 1.31.5 היא גרסת mainline שהפיצ'רים המרכזיים שלה הם:

  • Predicate variables ב-location – כל משתנה יכול לשמש כתנאי בהגדרת location.
  • קריאה מוקדמת של גוף הבקשה – הדירקטיבה client_body_early_read.
  • פענוח JSON נייטיב וחילוץ ערכים למשתנים – דרך מודול חדש.
  • NGINX Control API – ממשק שליטה חדש.

שלושת הראשונים הם מה שרלוונטי לאבטחת webhook ולולידציה ברמת ה-proxy. ה-Control API מעניין בפני עצמו, אבל הוא מחוץ לתחום המדריך.

nginx 1.31.5, לא 1.31.0

כותרות רבות ברשת מדברות על "nginx 1.31", אבל לפי דיון בפורום הקהילה של NGINX, מודול ה-JSON, ששמו ngx_http_json_module, נכנס בגרסה 1.31.5 שהוכרזה ב-2 בספטמבר 2026, ולא בגרסת הבסיס 1.31.0. מי שמריץ 1.31.0 עד 1.31.4 לא ימצא את הדירקטיבה.

זו גם גרסת mainline. הזמינות של המודול בענף ה-stable לא מתועדת במקורות הזמינים, ולכן כדאי להניח שבשלב זה מדובר רק ב-mainline.

מצב התיעוד והקוד

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

  • התיעוד הרשמי נמצא בכתובת nginx.org/en/docs/http/ngx_http_json_module.html, אבל בהתחלה הוא לא היה קיים ופורסם רק אחרי שמשתמש בפורום שאל עליו.
  • הקומיט שהוסיף את המודול הוא a1f4a61 עם ההודעה "Added the json parser module", מסביבות 24 באוגוסט.
  • מדובר בקובץ C של כ-900 שורות בלבד.

מודול קטן הוא יתרון מבחינת שטח תקיפה ותחזוקה, אבל הוא גם רמז לכך שהיכולות ממוקדות: חילוץ ערכים, לא מנוע JSON Schema מלא.

איך json_set nginx ו-client_body_early_read עובדים יחד

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

json_set: מ-JSON למשתנה nginx

הסיכום הקצר ביותר מגיע מתשובה בפורום הקהילה: בהינתן JSON כלשהו, json_set יוצרת משתנה nginx חדש שמחזיק ערך מסוים שפוענח מתוך ה-JSON.

בפועל זה אומר שאפשר לקחת שדה כמו event או type מגוף הבקשה, לשים אותו במשתנה כמו $wh_event, ולהשתמש בו בכל מקום שבו nginx מקבל משתנים: map, if, log_format, כותרות ל-upstream ועוד.

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

למה צריך client_body_early_read

זו הנקודה שהכי קל לפספס. לפי הבלוג של NGINX, הסדר ברירת המחדל הוא: כותרות, בחירת location, ורק אז הגוף. כלומר בזמן שבו nginx מחליט לאן הבקשה הולכת, הוא עדיין לא ראה את ה-payload.

הדירקטיבה client_body_early_read (שנוספה ב-PR ‏#1641 במאגר nginx/nginx) הופכת את הסדר: nginx מאחסן ב-buffer ומפענח את גוף הבקשה לפני ה-location matching. בלי זה, משתנה שתלוי בגוף לא יהיה זמין בשלב ההחלטה.

לקריאה מוקדמת יש מחיר: nginx חייב להחזיק את הגוף אצלו לפני שהוא ממשיך. בסעיף המגבלות נחזור לזה.

Predicate locations: ניתוב לפי משתנה

ה-PR ‏#1633 מאפשר להשתמש בכל משתנה כ-predicate בהגדרת location, לדוגמה location $is_ai_scraper {}. בשילוב עם קריאה מוקדמת של הגוף, אפשר לנתב לפי ערכים שחולצו מה-payload.

מה זה פותח עבור webhooks

  • דחייה של בקשות שחסר בהן שדה חובה, לפני שהן מגיעות ל-n8n.
  • ניתוב סוגי אירועים שונים ל-upstreams שונים (למשל אירועי תשלום לשירות אחד ואירועי CRM לאחר).
  • רישום ערכים מתוך ה-payload בלוג של nginx לצורכי דיבאג, בלי לגעת באפליקציה.
  • הפחתת עומס על תהליך Node יחיד או על slots של executions ב-n8n.

nginx webhook ולידציה בפועל: דחיית payload פגום לפני n8n או Node

החלק הזה בונה את הקונפיגורציה בשני שלבים: קודם בסיס יציב ל-n8n מאחורי reverse proxy לאוטומציות, ואז שכבת בדיקת JSON מעליו.

נקודת פתיחה: קונפיגורציית בסיס ל-n8n

מדריך קונפיגורציה מלא ל-n8n מאחורי nginx משתמש בהגבלת קצב של 10 בקשות לשנייה לכל IP עם burst=20 nodelay על /webhook/, ב-client_max_body_size 50m, ובזמני timeout של 300 שניות ל-proxy. זה בסיס סביר שאליו מוסיפים את בדיקת ה-JSON:

limit_req_zone $binary_remote_addr zone=n8n_webhook:10m rate=10r/s;

server {
    listen 443 ssl;
    server_name n8n.example.co.il;

    client_max_body_size 50m;

    location /webhook/ {
        limit_req zone=n8n_webhook burst=20 nodelay;

        proxy_pass http://127.0.0.1:5678;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;

        proxy_send_timeout 300s;
        proxy_read_timeout 300s;
    }

    location /webhook-test/ {
        limit_req zone=n8n_webhook burst=20 nodelay;
        proxy_pass http://127.0.0.1:5678;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
    }
}

שני נתיבים, לא אחד: לפי מדריך תקלות 404 ב-n8n, ‏/webhook/ משמש ל-production (ה-workflow חייב להיות Active), ו-/webhook-test/ משמש לבדיקות עם חלון האזנה של כ-120 שניות. צריך להחליט במודע אם הבדיקה חלה על שניהם או רק על production. החלה רק על production נוחה לפיתוח, אבל יוצרת פער: payload שעובר בבדיקה עלול להיחסם בפרודקשן.

בצד של n8n, התיעוד הרשמי מורה להגדיר את כתובת ה-webhook, לקבוע N8N_PROXY_HOPS=1, ולהעביר את כותרות X-Forwarded-For/Host/Proto. החל מ-n8n 2.35.0 המשתנה WEBHOOK_URL מסומן כ-deprecated ומוחלף ב-N8N_WEBHOOK_URL:

N8N_WEBHOOK_URL=https://n8n.example.co.il/
N8N_PROXY_HOPS=1

למי שמתחיל עם n8n, יש מדריך למתחילים שמסביר את מבנה ה-workflows וה-triggers לפני שנכנסים לשכבת התשתית.

הוספת בדיקת JSON

הקונפיגורציה הבאה ממחישה את הדפוס. התחביר של json_set ו-client_body_early_read בה הוא להמחשה בלבד ויש לאמת אותו מול nginx.org/en/docs/http/ngx_http_json_module.html ומול build של 1.31.5 ומעלה:

# ILLUSTRATIVE ONLY - verify directive names, argument order and context
# against nginx.org/en/docs/http/ngx_http_json_module.html

# Read and buffer the body before location matching
client_body_early_read on;

# Extract the "event" field from the JSON body into $wh_event
json_set $wh_event $request_body event;

map $wh_event $wh_missing_event {
    ""      1;
    default 0;
}

map $content_type $wh_bad_ctype {
    ~*^application/json  0;
    default              1;
}

server {
    listen 443 ssl;
    server_name n8n.example.co.il;
    client_max_body_size 50m;

    location /webhook/ {
        if ($wh_bad_ctype)     { return 415; }
        if ($wh_missing_event) { return 400; }

        limit_req zone=n8n_webhook burst=20 nodelay;
        proxy_pass http://127.0.0.1:5678;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
    }
}

כמה הערות על הדפוס:

  • map במקום לוגיקה מורכבת ב-if – ה-map מתרגם את הערך שחולץ לדגל 0/1, וה-if רק מחזיר קוד סטטוס. if שמכיל return בלבד הוא השימוש הבטוח והמקובל בתוך location.
  • בדיקת Content-Type נפרדת – זו בדיקה זולה שלא תלויה במודול החדש בכלל, ומסננת חלק ניכר מהרעש.
  • סדר שלבים – בדקו בפועל אם בקשה שנדחתה ב-return עדיין נספרת ב-limit_req. אם היא לא נספרת, תוקף ששולח זבל לא ייחסם על ידי הגבלת הקצב, אלא רק על ידי הבדיקה עצמה.
  • ערך ריק מול JSON שבור – לא מאומת שהמשתנה יהיה ריק כש-JSON לא תקין. ייתכן שההתנהגות שונה, ולכן בדיקות curl חובה.

חלופה שמנצלת את ה-predicate locations היא להגדיר משתנה $wh_invalid ב-map ולכתוב location $wh_invalid { return 400; }. התחביר הבסיסי מופיע בהכרזה הרשמית, אבל האינטראקציה בין predicate location לבין prefix locations קיימים לא מתועדת במקורות, ולכן הדפוס עם if שמוצג למעלה צפוי יותר בשלב זה.

מה נחשב payload פגום

כדאי להגדיר מראש מה בדיוק נחסם, ולא להגדיר את זה תוך כדי:

  1. גוף ריק בבקשת POST.
  2. Content-Type שאינו application/json.
  3. JSON שאינו ניתן לפענוח (סוגריים חסרים, פסיקים מיותרים).
  4. JSON תקין שחסר בו שדה חובה, כמו event או id.
  5. ערך בשדה מסוים שלא שייך לרשימה מוכרת (למשל סוג אירוע שה-workflow לא מטפל בו).

סעיפים 1 ו-2 אפשריים גם בלי המודול החדש. סעיפים 3 עד 5 הם מה ש-json_set מוסיף, בכפוף להתנהגות המדויקת שלו.

בדיקה עם curl

לפני כל reload בפרודקשן, מריצים סט בדיקות קבוע מול סביבת staging:

# Valid payload - expect 200 from n8n
curl -i -X POST https://staging.example.co.il/webhook/orders -H 'Content-Type: application/json' -d '{"event":"order.created","id":"123"}'

# Broken JSON - expect 400
curl -i -X POST https://staging.example.co.il/webhook/orders -H 'Content-Type: application/json' -d '{"event": "order.created"'

# Valid JSON, missing field - expect 400
curl -i -X POST https://staging.example.co.il/webhook/orders -H 'Content-Type: application/json' -d '{"id":"123"}'

# Wrong content type - expect 415
curl -i -X POST https://staging.example.co.il/webhook/orders -H 'Content-Type: text/plain' -d 'hello'

# Hebrew UTF-8 content - expect 200
curl -i -X POST https://staging.example.co.il/webhook/orders -H 'Content-Type: application/json' -d '{"event":"order.created","customer":"ישראל ישראלי"}'

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

אותו דפוס מול backend של Node

הקונפיגורציה זהה כשה-upstream הוא שרת Node במקום n8n: מחליפים את proxy_pass ואת הנתיבים. ההבדל הוא באחריות. nginx מסנן את מה שברור שהוא זבל, ו-Node ממשיך לבצע ולידציה מלאה של המבנה. לבחירת ספרייה לשכבה הזאת, יש השוואה בין Zod, Valibot ו-ArkType.

ביצועים: טענת פי 13 ואיך למדוד בעצמכם

המספר שמסתובב ברשת מגיע מכותרת של פוסט ב-dev.to: ‏json_set דוחה payload פגום בערך פי 13 מהר יותר מאשר העברתו הלאה ל-backend.

מה ידוע ומה לא

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

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

למה הכיוון הגיוני גם בלי המספר

גם בלי לסמוך על המספר המדויק, ההיגיון ברור. בקשה שנדחית ב-nginx חוסכת:

  • פתיחת חיבור ל-upstream או שימוש בחיבור קיים.
  • פענוח מחדש של ה-JSON ב-runtime של Node.
  • יצירת execution ב-n8n, כולל שמירה במסד הנתונים ושורות לוג.
  • הקצאת זיכרון בתהליך האפליקציה.

הפער בפועל תלוי מאוד במה שה-backend עושה. שרת Node ריק שמחזיר 400 מיד יהיה קרוב יותר ל-nginx, בעוד ש-workflow של n8n שנכשל אחרי כמה nodes יהיה רחוק בהרבה.

איך מריצים benchmark הוגן

מומלץ להריץ מדידה עצמאית בסביבת staging שדומה לפרודקשן. דפוס אפשרי, עם כלי עומס כמו hey:

# A: bad payload rejected at nginx (location with enforcement)
hey -n 5000 -c 50 -m POST -T application/json -d '{"id":"1"}' https://staging.example.co.il/webhook-enforced/test

# B: same bad payload forwarded to n8n (location without enforcement)
hey -n 5000 -c 50 -m POST -T application/json -d '{"id":"1"}' https://staging.example.co.il/webhook-passthrough/test

כמה כללים למדידה שאפשר לסמוך עליה:

  1. אותה מכונה, אותו payload ואותה רמת מקביליות בשני התרחישים.
  2. השבתת limit_req בזמן המדידה, אחרת הגבלת הקצב תעוות את התוצאות.
  3. כמה גדלי payload: קטן (מאות בתים), בינוני (עשרות KB) וגדול (קרוב ל-client_max_body_size).
  4. הרצת חימום לפני המדידה האמיתית.
  5. דיווח על p50 ו-p99, לא רק על ממוצע.

מה למדוד מעבר ל-latency

זמן התגובה הוא רק חלק מהסיפור. כדאי לעקוב גם אחרי צריכת CPU וזיכרון של תהליך n8n או Node, מספר ה-executions שנוצרו ב-n8n, נפח הלוגים, וצריכת הזיכרון של nginx עצמו כשהוא מאחסן גופים ב-buffer. ייתכן שה-latency משתפר אבל צריכת הזיכרון של ה-proxy עולה, וזה טרייד-אוף שצריך לראות במספרים.

מגבלות: מה ולידציית JSON ב-nginx לא עושה

ולידציית JSON ב-nginx היא מסננת גסה. היא לא מחליפה אף שכבה קיימת, והיא מוסיפה כמה סיכונים משלה.

היא לא מחליפה אבטחת webhook מבוססת HMAC

הדפוס המקובל לאימות מקור של webhook הוא חתימת HMAC: השולח חותם על ה-payload (למשל בכותרת X-Hub-Signature-256 של GitHub), והמקבל מחשב מחדש את החתימה ומשווה. זה מה שמוכיח שהבקשה באמת הגיעה מהשולח ושהתוכן לא שונה בדרך.

בדיקה ש-JSON מכיל שדה event לא מוכיחה כלום על המקור. תוקף שמכיר את מבנה ה-payload יעבור את הבדיקה בקלות. לכן אימות החתימה חייב להישאר באפליקציה. מאמר על gateways של n8n ו-nginx ממליץ לבצע אותו ב-Function node, לצד דפוס של fast-ack ו-idempotency.

היא לא schema validation

מהתיאור הזמין, json_set מחלצת ערך למשתנה. אין במקורות אינדיקציה לתמיכה ב-JSON Schema, בבדיקת טיפוסים, בטווחי ערכים או במבנים מקוננים מורכבים. כל מה שמעבר ל"השדה קיים ויש לו ערך מוכר" שייך לאפליקציה.

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

buffering, גודל גוף וזיכרון

client_body_early_read מחייבת את nginx לאחסן את הגוף ב-buffer ולפענח אותו לפני בחירת ה-location. המשמעויות המעשיות:

  • webhooks עם קבצים מצורפים גדולים ייקראו במלואם לפני כל החלטה.
  • ה-client_max_body_size 50m מהקונפיגורציה הבסיסית הופך לתקרה של זיכרון או דיסק לכל בקשה בו-זמנית.
  • האינטראקציה עם proxy_request_buffering ועם webhooks שמזרימים קבצים לא מתועדת במקורות.
  • מגבלות על עומק קינון ועל צריכת הזיכרון של הפרסר לא מוזכרות במקורות.

ההמלצה המעשית: להפעיל קריאה מוקדמת ובדיקת JSON רק על נתיבי webhook שבהם ה-payload קטן וצפוי, ולהוריד את client_max_body_size בנתיבים האלה לערך שתואם את הגודל האמיתי.

ניסיונות חוזרים מצד השולח

קוד 400 שמוחזר על payload שהשולח רואה כתקין הוא בעיה מסוג אחר. ספקים שונים מגיבים אחרת לשגיאות 4xx: חלקם מוותרים, חלקם מנסים שוב, וחלקם משביתים את ה-webhook אחרי סדרת כישלונות. חסימה שגויה של אירועי תשלום עלולה להיות שקטה ויקרה. לכן חשוב לשלב idempotency keys בצד המקבל ולהבין איך ניסיונות חוזרים יכולים להפוך ל-retry storm.

פריסה בטוחה: log-only, canary ואז אכיפה

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

שלב 0: לוודא שהגרסה נכונה

לפני הכול מוודאים שה-build הוא 1.31.5 ומעלה ושהקונפיגורציה עוברת בדיקת תחביר:

nginx -v
nginx -t && nginx -s reload

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

שלב 1: מצב log-only

מחלצים את הערכים ורושמים אותם, בלי לחסום אף בקשה:

log_format webhook_audit '$remote_addr [$time_local] "$request" '
                         'status=$status event="$wh_event" '
                         'missing=$wh_missing_event ctype="$content_type"';

location /webhook/ {
    access_log /var/log/nginx/webhook_audit.log webhook_audit;
    # observe only - no return here yet
    proxy_pass http://127.0.0.1:5678;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Host $host;
}

משאירים את המצב הזה לפחות שבוע, או מספיק זמן כדי לכסות את כל סוגי האירועים (כולל אירועים חודשיים כמו חידוש מנוי). אחר כך בודקים: כמה בקשות היו מסומנות missing=1? האם כולן באמת זבל, או שיש ביניהן אירועים לגיטימיים עם מבנה אחר? האם payloads בעברית מחולצים כראוי?

שלב 2: canary על webhook אחד

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

# Enforce only on one low-risk webhook path
location = /webhook/contact-form-id {
    if ($wh_missing_event) { return 400; }
    proxy_pass http://127.0.0.1:5678;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Host $host;
}

# All other webhooks stay in log-only mode
location /webhook/ {
    access_log /var/log/nginx/webhook_audit.log webhook_audit;
    proxy_pass http://127.0.0.1:5678;
}

ה-location = מנצח התאמת prefix, כך שרק הנתיב הספציפי נאכף. עוקבים אחרי מספר ה-400 שמוחזרים, ומשווים לנתוני n8n: האם כמות ה-executions הלגיטימיים נשארה זהה?

שלב 3: אכיפה מלאה

רק אחרי שה-canary יציב מרחיבים את האכיפה לכל /webhook/. בשלב הזה מחליטים גם לגבי /webhook-test/. ההמלצה הכללית היא להחיל את אותה בדיקה גם עליו, כדי שבדיקות בפיתוח ישקפו את מה שקורה בפרודקשן.

rollback וניטור

שומרים את קובץ הקונפיגורציה הקודם בצד, כך ש-rollback הוא העתקה ו-nginx -s reload. במקביל מגדירים התראה על קפיצה בשיעור ה-400 בנתיבי webhook. חסימה שגויה נראית מבחוץ בדיוק כמו workflow שהפסיק לרוץ, ולכן כדאי לשלב ניטור heartbeat ל-workflows ב-n8n שיזהה שקט חשוד.

המודול הנייטיב, מודול GetPageSpeed או ולידציה באפליקציה

המודול הנייטיב הוא לא האפשרות היחידה לפענוח JSON ב-nginx. קיים גם מודול צד שלישי של GetPageSpeed עם שם דומה, ngx_http_json_module, אבל זה מוצר אחר לגמרי. הוא מבוסס על ספריית jansson ועל NDK, ומציע דירקטיבות בשם json_loads ו-json_dumps. במערכות מבוססות RHEL צריך לטעון קודם את NDK עם load_module ורק אחריו את מודול ה-JSON.

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

קריטריון

מודול נייטיב (1.31.5)

מודול GetPageSpeed

ולידציה באפליקציה

זמינות

ליבת קוד פתוח, mainline בלבד

חבילות מוכנות גם לגרסאות ישנות

כל גרסה

תלויות

אין

NDK ו-jansson

ספריית ולידציה באפליקציה

דירקטיבות

json_set

json_loads, json_dumps

לא רלוונטי

דחייה לפני upstream

כן

כן

לא

אימות HMAC

לא

לא

כן

ולידציית schema מלאה

לא מתועד

לא מתועד

כן

בשלות תיעוד

חדש, פורסם לאחרונה

שלבי התקנה מתועדים

תלוי בספרייה

רישוי

קוד פתוח

שימוש מסחרי בפרודקשן דורש מנוי

תלוי בספרייה

ההשוואה מבוססת על ההכרזה של NGINX, על עמוד המודול של GetPageSpeed ועל מאמר ה-gateway ל-n8n.

איך בוחרים

  • שרת חדש שאפשר להריץ עליו mainline – המודול הנייטיב, בלי תלויות חיצוניות.
  • שרת יציב שאסור לשדרג ל-mainline – המודול החיצוני הוא אפשרות, בכפוף לתנאי הרישוי. חשוב לזכור שהקונפיגורציות לא ניידות בין שני המודולים, כי הדירקטיבות שונות.
  • בכל מקרה – האפליקציה ממשיכה לבצע אימות חתימה, ולידציית schema ו-idempotency. ה-proxy רק מוריד ממנה עומס.

שאלות נפוצות

באיזו גרסת nginx הופיעה json_set?

מודול ה-JSON הופיע בגרסת mainline ‏1.31.5, שהוכרזה ב-2 בספטמבר 2026, ולא ב-1.31.0. הדירקטיבה שלו היא json_set. זמינות בענף ה-stable לא מתועדת בשלב זה.

האם חייבים את client_body_early_read?

כדי לקבל החלטות לפי תוכן הגוף לפני בחירת ה-location, כן. הדירקטיבה גורמת ל-nginx לאחסן ולפענח את הגוף לפני ה-location matching, בניגוד לסדר ברירת המחדל שבו הגוף נקרא רק בסוף.

האם שיפור הביצועים של פי 13 אמין?

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

האם ולידציה ב-proxy מחליפה אימות חתימה?

לא. אימות חתימת HMAC, כמו X-Hub-Signature-256 של GitHub, מוכיח מקור ושלמות של ה-payload. בדיקת מבנה ב-nginx רק מסננת בקשות שבורות, ואימות החתימה חייב להישאר אצל המקבל.

אילו נתיבי n8n כדאי להגן?

webhooks של production משתמשים ב-/webhook/ ו-webhooks של בדיקה ב-/webhook-test/, לפי מדריך התקלות של n8n מאחורי proxy. מומלץ להחיל את אותה בדיקה על שניהם כדי למנוע פערים בין בדיקות לפרודקשן, או להחליט במודע להחיל אותה רק על production.

אילו הגדרות n8n נדרשות מאחורי nginx?

לפי התיעוד של n8n: להגדיר N8N_WEBHOOK_URL (המשתנה WEBHOOK_URL מסומן כ-deprecated החל מ-n8n 2.35.0), לקבוע N8N_PROXY_HOPS=1, ולהעביר את כותרות X-Forwarded-For, X-Forwarded-Host ו-X-Forwarded-Proto.

סיכום

nginx 1.31.5 מביא לליבת הקוד הפתוח שלושה רכיבים שחסרו שנים: client_body_early_read שקוראת את הגוף לפני בחירת ה-location, מודול JSON נייטיב עם json_set שמחלצת ערכים למשתנים, ו-predicate locations שמאפשרות להחליט לפי המשתנים האלה. יחד הם מאפשרים לדחות payloads פגומים של webhooks עוד לפני שהם צורכים משאבים ב-n8n או ב-Node.

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

הדרך הנכונה להשתמש ביכולת היא כמסננת גסה בלבד: בסיס יציב של rate limiting וכותרות forwarded, מצב log-only שמראה מה הייתה החסימה תופסת, canary על webhook אחד בסיכון נמוך, ורק אז אכיפה מלאה. אימות HMAC, ולידציית schema ו-idempotency נשארים באפליקציה. לצוותים בישראל שמריצים n8n על VPS מול סליקה, CRM ווואטסאפ, כדאי לכלול payloads בעברית בכל סבב בדיקות ולשמור את בלוקי הקונפיגורציה בכיוון LTR בתיעוד הפנימי.

מקורות

וואטסאפ