NueForm

Testing Webhooks

ngrok, webhook.site, curl, और NueForm API उपयोग करके local development के दौरान NueForm webhooks test करने का तरीका।

Development के दौरान webhooks test करने के लिए आपके endpoint को public internet से reachable होना चाहिए। यह guide quick inspection tools से लेकर full local development setups तक कई approaches cover करती है।

Option 1: webhook.site (Quick Inspection)

webhook.site एक temporary public URL provide करता है जो incoming HTTP requests capture और display करता है। बिना कोई code लिखे NueForm क्या भेजता है यह देखने का यह सबसे तेज़ तरीका है।

  1. webhook.site पर जाएं।
  2. Unique URL copy करें (जैसे, https://webhook.site/abc123-def456-...)।
  3. इसे अपने form के webhook URL के रूप में set करें:
bash
curl -X PUT https://app.nueform.com/api/v1/webhooks/form/YOUR_FORM_ID \
  -H "Authorization: Bearer nf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://webhook.site/abc123-def456-..." }'
  1. अपने form पर response submit करें।
  2. Captured request देखने के लिए webhook.site refresh करें, जिसमें headers, body, और X-NueForm-Signature शामिल हैं।

webhook.site inspection के लिए बढ़िया है लेकिन custom verification logic run करने की अनुमति नहीं देता। Payload format समझने के लिए इसका उपयोग करें, फिर full testing के लिए local server पर move करें।

Option 2: ngrok (Local Development)

ngrok public URL से आपकी local machine तक secure tunnel बनाता है। इससे आप अपने development server पर real webhook deliveries receive कर सकते हैं।

Setup

  1. ngrok install करें:
bash
# macOS (Homebrew)
brew install ngrok

# Or download from https://ngrok.com/download
  1. अपना local webhook server start करें (जैसे, port 3001 पर):
bash
node server.js
# or
python app.py
  1. ngrok tunnel start करें:
bash
ngrok http 3001
  1. ngrok output से HTTPS forwarding URL copy करें:
text
Forwarding  https://a1b2c3d4.ngrok-free.app -> http://localhost:3001
  1. ngrok URL को अपने webhook endpoint के रूप में set करें:
bash
curl -X PUT https://app.nueform.com/api/v1/webhooks/form/YOUR_FORM_ID \
  -H "Authorization: Bearer nf_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://a1b2c3d4.ngrok-free.app/webhooks/nueform" }'
  1. अपने form पर response submit करें। Webhook आपके local server पर आएगा।

Traffic Inspect करना

ngrok http://localhost:4040 पर local web interface provide करता है जहां आप tunnel से गुज़रने वाले सभी requests inspect, replay, और headers और response codes देख सकते हैं।

Free ngrok URLs हर बार ngrok restart करने पर बदल जाते हैं। नया tunnel URL मिलने पर NueForm में अपना webhook URL update करना याद रखें। Stable subdomain के लिए paid ngrok plan upgrade करने पर विचार करें।

Option 3: curl (Payloads Simulate करना)

आप NueForm से गुज़रे बिना अपने local server पर test webhook payloads भेजने के लिए curl उपयोग कर सकते हैं। यह isolation में आपकी verification और processing logic test करने के लिए उपयोगी है।

Signed Test Payload Generate करना

पहले, test payload बनाएं और अपने webhook secret से sign करें:

bash
# Your webhook secret (from the NueForm API or dashboard)
SECRET="a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2"

# The test payload
PAYLOAD='{
  "event": "form.submitted",
  "formId": "507f1f77bcf86cd799439011",
  "formTitle": "Test Form",
  "responseId": "507f1f77bcf86cd799439022",
  "answers": [
    { "questionId": "507f1f77bcf86cd799439033", "value": "Test answer" },
    { "questionId": "507f1f77bcf86cd799439044", "value": 5 }
  ],
  "submittedAt": "2025-03-15T14:32:07.123Z"
}'

# Compute the HMAC-SHA256 signature
SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

echo "Signature: $SIGNATURE"

Signed Request भेजना

bash
curl -X POST http://localhost:3001/webhooks/nueform \
  -H "Content-Type: application/json" \
  -H "X-NueForm-Signature: $SIGNATURE" \
  -d "$PAYLOAD"

One-Liner

सब कुछ single command में combine करें:

bash
SECRET="your_secret_here"
PAYLOAD='{"event":"form.submitted","formId":"507f1f77bcf86cd799439011","formTitle":"Test Form","responseId":"507f1f77bcf86cd799439022","answers":[{"questionId":"q1","value":"hello"}],"submittedAt":"2025-03-15T14:32:07.123Z"}'
SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

curl -X POST http://localhost:3001/webhooks/nueform \
  -H "Content-Type: application/json" \
  -H "X-NueForm-Signature: $SIGNATURE" \
  -d "$PAYLOAD"

Signature Rejection Test करना

यह verify करने के लिए कि आपका endpoint invalid signatures को correctly reject करता है, गलत signature के साथ request भेजें:

bash
curl -X POST http://localhost:3001/webhooks/nueform \
  -H "Content-Type: application/json" \
  -H "X-NueForm-Signature: 0000000000000000000000000000000000000000000000000000000000000000" \
  -d '{"event":"form.submitted","formId":"test","formTitle":"Test","responseId":"test","answers":[],"submittedAt":"2025-03-15T14:32:07.123Z"}'

आपके endpoint को 401 Unauthorized return करना चाहिए।

Option 4: Node.js Test Script

Test payloads sign और send करने के लिए standalone Node.js script बनाएं:

javascript
import crypto from 'crypto';

const SECRET = process.env.NUEFORM_WEBHOOK_SECRET || 'your_secret_here';
const ENDPOINT = process.env.WEBHOOK_URL || 'http://localhost:3001/webhooks/nueform';

const payload = JSON.stringify({
  event: 'form.submitted',
  formId: '507f1f77bcf86cd799439011',
  formTitle: 'Customer Feedback Survey',
  responseId: crypto.randomUUID().replace(/-/g, '').slice(0, 24),
  answers: [
    { questionId: 'q_name', value: 'Jane Doe' },
    { questionId: 'q_email', value: 'jane@example.com' },
    { questionId: 'q_rating', value: 4 },
    { questionId: 'q_feedback', value: 'Great product!' },
    { questionId: 'q_features', value: ['Feature A', 'Feature C'] },
  ],
  submittedAt: new Date().toISOString(),
});

const signature = crypto
  .createHmac('sha256', SECRET)
  .update(payload)
  .digest('hex');

const response = await fetch(ENDPOINT, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-NueForm-Signature': signature,
  },
  body: payload,
});

console.log(`Status: ${response.status}`);
console.log(`Body: ${await response.text()}`);

इसे इस प्रकार run करें:

bash
NUEFORM_WEBHOOK_SECRET=your_secret node test-webhook.mjs

Option 5: Real Submission Trigger करना

Test करने का सबसे thorough तरीका अपने form पर actual response submit करना है:

  1. अपना webhook URL (per-form या global) अपने test endpoint पर point करने के लिए configure करें।
  2. अपना published form browser में खोलें।
  3. Form भरें और submit करें।
  4. अपने endpoint पर webhook delivery observe करें।

यह पूरी pipeline end-to-end test करता है, जिसमें answer validation, quiz scoring, और NueForm द्वारा generate किया जाने वाला actual payload शामिल है।

Failed Deliveries Debug करना

यदि आपका webhook endpoint requests receive नहीं कर रहा, इस checklist से काम करें:

1. URL configured होने की verify करें

bash
# Check per-form webhook
curl https://app.nueform.com/api/v1/webhooks/form/YOUR_FORM_ID \
  -H "Authorization: Bearer nf_your_api_key"

# Check global webhooks
curl https://app.nueform.com/api/v1/webhooks/global \
  -H "Authorization: Bearer nf_your_api_key"

2. URL reachable होने की verify करें

bash
# Test that your endpoint accepts POST requests
curl -X POST https://your-endpoint.com/webhooks/nueform \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

3. Webhook secret check करें

Webhooks केवल तभी dispatch होते हैं जब आपके account में webhook secret set हो। Verify करें:

bash
curl https://app.nueform.com/api/v1/webhooks/secret \
  -H "Authorization: Bearer nf_your_api_key"

यदि response secret दिखाता है, तो ठीक है। यदि नहीं, इस request द्वारा एक auto-generate होगा।

4. अपना plan check करें

Webhooks के लिए Pro plan या higher आवश्यक है। अपने account settings में NueForm dashboard पर अपना plan status verify करें।

5. Timeout check करें

NueForm का 5-second timeout है। यदि आपका endpoint respond करने में अधिक समय लेता है, request abort हो जाएगी। सुनिश्चित करें कि आप तुरंत 200 OK return करें और data background में process करें।

6. Firewall और network rules check करें

सुनिश्चित करें कि आपका server external sources से incoming POST requests allow करता है। यदि आप firewall या VPN के पीछे हैं, NueForm के IP ranges allowlist करने या ngrok उपयोग करने की आवश्यकता हो सकती है।

Common Testing Mistakes

MistakeSolution
Signature verification से पहले express.json() middleware उपयोग करनाWebhook route पर express.raw({ type: 'application/json' }) उपयोग करें
Revoked या expired API key से test करनाFresh API key generate करें
Global webhooks enable करना भूलनाप्रत्येक global webhook entry पर "enabled": true set करें
Webhook URL के लिए HTTPS की बजाय HTTP उपयोग करनाNueForm आपके provide किए URL पर भेजता है, लेकिन production में HTTPS उपयोग करें
Webhook secret check न करनाDeliveries expect करने से पहले सुनिश्चित करें कि आपके account में webhook secret है

Next Steps

  • Overview --- NueForm में webhooks कैसे काम करते हैं
  • Payloads --- Payload format समझें
  • Verification --- Signature verification implement करें
अंतिम अपडेट: 6 अप्रैल 2026