वेबहुक सेट करना और सिग्नेचर जाँचना.

इवेंट

वेबहुक आपके सर्वर का एक पता है, जिस पर हम कोई इवेंट होते ही उसे भेजते हैं। छह इवेंट हैं:

form.response.created   Eine neue Antwort auf eines deiner Formulare
form.response.updated   Jemand hat seine Antwort über den Bearbeitungslink geändert
order.paid              Eine Bestellung ist bezahlt
order.fulfilled         Eine Bestellung ist versendet oder übergeben
order.canceled          Eine bestätigte Bestellung wurde storniert
order.refunded          Eine Bestellung wurde erstattet

order.refunded पहले आंशिक रिफ़ंड पर और पूरे रिफ़ंड पर आता है। जिस चेकआउट का कभी भुगतान नहीं हुआ और जो समाप्त हो जाता है, वह रद्दीकरण नहीं है — उसके लिए कोई इवेंट नहीं आता।

वेबहुक सेट अप करना

प्रोग्राम खुद भी वेबहुक दर्ज कर सकते हैं: POST /v1/webhooks ऐसी कुंजी के साथ, जिसमें webhooks:manage हो — और साथ में उस डेटा को पढ़ने का अधिकार भी, जिसे वेबहुक भेजता है (फ़ॉर्म इवेंट के लिए forms:read, ऑर्डर के लिए orders:read)।

1. 1डैशबोर्ड में डेवलपर सेक्शन खोलें।
2. 2“वेबहुक” के अंतर्गत अपने रिसीवर का पता दर्ज करें — यह https से शुरू होता है।
3. 3“कौन-से इवेंट?” के अंतर्गत चुनें कि आप क्या प्राप्त करना चाहते हैं, और “वेबहुक बनाएँ” पर क्लिक करें।
4. 4इसके बाद दिखाई देने वाले सीक्रेट को कॉपी करके अपने रिसीवर में डालें।
5. 5“टेस्ट भेजें” पर क्लिक करें — परिणाम तुरंत उसके नीचे दिखाई देता है।

क्या पहुँचता है

हर इवेंट JSON के साथ एक POST होता है। data.object में ऑब्जेक्ट उसी रूप में होता है जैसा API में — ऑर्डर वैसा ही जैसा GET /v1/orders/{id} में, जवाब वैसा ही जैसा जवाबों की सूची में। फ़ॉर्म इवेंट में data.form में यह भी बताया जाता है कि जवाब किस फ़ॉर्म का है।

{
  "id": "evt_Q2x9kLmP4vT7aB1cD3eF5gH7",
  "object": "event",
  "type": "order.paid",
  "api_version": "2026-09-23",
  "created_at": "2026-09-23T14:05:12Z",
  "data": {
    "object": {
      "id": 5531,
      "object": "order",
      "number": 42,
      "status": "confirmed",
      "payment_status": "paid",
      "currency": "EUR",
      "total": 3890,
      "customer": { "email": "mara@example.com", "name": "Mara Sol" },
      "items": [
        { "name": "Kaffeebohnen, 500 g", "sku": "KAF-500", "quantity": 2, "unit_price": 1690 }
      ]
    }
  }
}

सिग्नेचर की जाँच करना

हर कॉल में हेडर KENJTEC-Signature: t=<समय>,v1=<सिग्नेचर> होता है। सिग्नेचर एक HMAC-SHA256 है, जो समय, एक बिंदु और अनुरोध की अपरिवर्तित बॉडी पर बनाया जाता है — आपके वेबहुक के सीक्रेट को कुंजी के रूप में इस्तेमाल करके। जिस किसी चीज़ का समय पाँच मिनट से अधिक पुराना हो, उसे अस्वीकार कर दें।

JSON पार्स करने से पहले रॉ बॉडी के आधार पर जाँच करें: एक भी अलग स्पेस से अलग सिग्नेचर बनता है। सीक्रेट आपको किसी भी समय “सीक्रेट दिखाएँ” के अंतर्गत मिल जाता है; “सीक्रेट नवीनीकृत करें” पुराने सीक्रेट को तुरंत अमान्य कर देता है।

import crypto from "node:crypto";

// raw: the unparsed request body (Buffer), header: the KENJTEC-Signature header
export function verify(raw, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
  const expected = crypto.createHmac("sha256", secret)
    .update(`${parts.t}.`).update(raw).digest("hex");
  const given = String(parts.v1 ?? "");
  return given.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(given));
}

import hashlib, hmac, time

def verify(raw: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    if abs(time.time() - int(parts["t"])) > 300:
        return False
    expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts.get("v1", ""))

एक ही इवेंट दो बार पहुँच सकता है — जैसे जब आपका सर्वर जवाब देता है, लेकिन वह जवाब हम तक नहीं पहुँचता। id में मौजूद पहचान (हेडर KENJTEC-Event-Id में भी) इस दौरान वही रहती है: इसे याद रखें और हर इवेंट को केवल एक बार प्रोसेस करें।

जब कुछ नहीं पहुँचता

दस सेकंड के भीतर 200 से 299 तक के स्टेटस वाला हर जवाब पहुँचा हुआ माना जाता है। हम रीडायरेक्ट का पालन नहीं करते।

अगर कोई इवेंट नहीं पहुँचता, तो हम फिर से कोशिश करते हैं: 1, 5 और 30 मिनट के बाद, 2, 6 और 12 घंटे के बाद और दो बार 24 घंटे के बाद — तीन दिन से कुछ अधिक समय तक। अगर लगातार पाँच इवेंट अंततः नहीं पहुँचते, तो हम वेबहुक बंद कर देते हैं; तब डैशबोर्ड में इसका कारण दिखाया जाता है, और “फिर से चालू करें” उसे रीसेट कर देता है।

“लॉग” के अंतर्गत आप पिछले 30 दिनों की हर डिलीवरी को स्टेटस और कंटेंट के साथ देख सकते हैं। वहाँ से हर इवेंट को “फिर से भेजें” के ज़रिए दोबारा भेजा जा सकता है।

वेबहुक केवल सार्वजनिक https पतों पर जाते हैं। आंतरिक नेटवर्क के पते और स्वयं KENJTEC के पते हम स्वीकार नहीं करते।