मुख्य सामग्री पर जाएं

​
Webhooks

Webhooks आपको अपने WhatsApp instances पर events होने पर real-time HTTP callbacks प्राप्त करने की सुविधा देते हैं। API को poll करने के बजाय, Wappfy events को आपके server पर push करता है जैसे ही वे होते हैं।

​
Supported Events

Wappfy 12 webhook event types को support करता है:
Eventविवरण
message.receivedएक नया inbound message प्राप्त हुआ।
message.sentएक outbound message सफलतापूर्वक भेजा गया।
message.deliveredभेजा गया message प्राप्तकर्ता के device पर deliver हुआ (double check mark)।
message.readभेजा गया message प्राप्तकर्ता द्वारा पढ़ा गया (blue check marks)।
message.failedएक outbound message भेजने में विफल रहा।
message.reactionकिसी ने message पर emoji से react किया।
Eventविवरण
instance.connectedएक instance सफलतापूर्वक WhatsApp से connect हो गया।
instance.disconnectedएक instance ने अपना WhatsApp connection खो दिया।
instance.qrScanning के लिए एक नया QR code उपलब्ध है।
Eventविवरण
group.joinedएक participant group में शामिल हुआ (bot स्वयं सहित)।
group.leftएक participant ने group छोड़ा।
contact.createdएक नया contact save या detect किया गया।

​
एक Webhook बनाएं

Events प्राप्त करना शुरू करने के लिए webhook endpoint register करें। 
curl -X POST https://api.wappfy.io/api/webhooks \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhooks/wappfy",
    "events": ["message.received", "message.sent", "message.delivered"],
    "instance_id": "inst_abc123",
    "secret": "whsec_my_signing_secret",
    "retry_count": 3,
    "timeout_ms": 10000
  }'
Response: 
{
  "data": {
    "id": "wh_xyz789",
    "url": "https://your-server.com/webhooks/wappfy",
    "events": ["message.received", "message.sent", "message.delivered"],
    "instance_id": "inst_abc123",
    "is_active": true,
    "retry_count": 3,
    "timeout_ms": 10000,
    "created_at": "2026-02-10T12:00:00Z"
  }
}

​
Configuration Options

FieldTypeDefaultविवरण
urlstringआवश्यकवह HTTPS URL जो webhook POST requests प्राप्त करेगा।
eventsstring[]आवश्यकSubscribe करने के लिए event types की array।
instance_idstringnullWebhook को किसी specific instance तक सीमित करें। यदि null है, तो सभी instances से events प्राप्त होंगे।
secretstringnullPayload verification के लिए HMAC signatures generate करने में उपयोग किया जाने वाला secret।
retry_countnumber3Delivery failure पर retry attempts की संख्या (0-5)।
timeout_msnumber10000Milliseconds में request timeout (1000-30000)।
instance_id field वैकल्पिक है। यदि छोड़ दिया जाए, तो webhook आपके account की सभी instances से events प्राप्त करेगा।

​
Webhooks की सूची

curl https://api.wappfy.io/api/webhooks \
  -H "X-Api-Key: YOUR_API_KEY"
Response: 
{
  "data": [
    {
      "id": "wh_xyz789",
      "url": "https://your-server.com/webhooks/wappfy",
      "events": ["message.received", "message.sent", "message.delivered"],
      "instance_id": "inst_abc123",
      "is_active": true,
      "retry_count": 3,
      "timeout_ms": 10000
    }
  ]
}

​
एक Webhook Update करें

किसी मौजूदा webhook का URL, events, या configuration update करें। 
curl -X PATCH https://api.wappfy.io/api/webhooks/wh_xyz789 \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["message.received", "message.sent", "message.delivered", "message.read"],
    "is_active": true
  }'

​
एक Webhook Delete करें

curl -X DELETE https://api.wappfy.io/api/webhooks/wh_xyz789 \
  -H "X-Api-Key: YOUR_API_KEY"

​
Delivery Payload Format

जब कोई event होता है, Wappfy आपके webhook URL पर निम्न structure के साथ एक POST request भेजता है: 
{
  "id": "dlv_abc123def456",
  "event": "message.received",
  "instance_id": "inst_abc123",
  "timestamp": "2026-02-10T14:30:00Z",
  "data": {
    "message_id": "BAE5F2C4D3B2A1",
    "chat_id": "[email protected]",
    "from": "[email protected]",
    "type": "text",
    "text": "Hello!",
    "timestamp": "2026-02-10T14:30:00Z"
  }
}

​
Payload Fields

Fieldविवरण
idUnique delivery ID। Deduplication के लिए इसका उपयोग करें।
eventवह event type जिसने इस delivery को trigger किया।
instance_idवह instance जिसने event generate किया।
timestampISO 8601 timestamp जब event हुआ।
dataEvent-specific payload। सामग्री event type के अनुसार भिन्न होती है।

​
HMAC Signature Verification

यदि आपने webhook बनाते समय secret प्रदान किया है, तो प्रत्येक delivery में X-Wappfy-Signature header शामिल होगा जिसमें request body का HMAC-SHA256 signature होगा। यह सुनिश्चित करने के लिए हमेशा इस signature को verify करें कि request Wappfy से आई है और उसमें छेड़छाड़ नहीं की गई है।

​
Verification उदाहरण

const crypto = require("crypto");

function verifyWebhookSignature(req, secret) {
  const signature = req.headers["x-wappfy-signature"];
  if (!signature) return false;

  const expectedSignature = crypto
    .createHmac("sha256", secret)
    .update(JSON.stringify(req.body))
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// Express middleware
app.post("/webhooks/wappfy", (req, res) => {
  const isValid = verifyWebhookSignature(req, "whsec_my_signing_secret");

  if (!isValid) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  const { event, data } = req.body;
  console.log(`Received event: ${event}`, data);

  // Always respond with 200 quickly to prevent retries
  res.status(200).json({ received: true });
});
Timing attacks से बचने के लिए signatures verify करते समय हमेशा constant-time comparison (जैसे timingSafeEqual या hmac.compare_digest) का उपयोग करें।

​
Retry Behavior

यदि आपका server configured timeout_ms के भीतर 2xx status code से respond नहीं करता, तो Wappfy delivery को retry करेगा।
AttemptDelay
पहला retry10 seconds
दूसरा retry60 seconds
तीसरा retry5 minutes
चौथा retry30 minutes
पांचवां retry2 hours
2xx response प्राप्त होने या retry_count समाप्त होने पर retries रुक जाते हैं। Default retry count 3 है।

​
Delivery History देखना

पिछले delivery attempts और उनके results देखने के लिए webhook का delivery log जांचें। 
curl https://api.wappfy.io/api/webhooks/wh_xyz789/deliveries \
  -H "X-Api-Key: YOUR_API_KEY"
Response: 
{
  "data": [
    {
      "id": "dlv_abc123def456",
      "event": "message.received",
      "status": "delivered",
      "http_status": 200,
      "attempts": 1,
      "created_at": "2026-02-10T14:30:00Z",
      "delivered_at": "2026-02-10T14:30:01Z"
    },
    {
      "id": "dlv_ghi789jkl012",
      "event": "message.sent",
      "status": "failed",
      "http_status": 500,
      "attempts": 3,
      "created_at": "2026-02-10T14:31:00Z",
      "last_error": "Server returned 500 Internal Server Error"
    }
  ]
}

​
Event Payload उदाहरण

{
  "id": "dlv_abc123",
  "event": "message.received",
  "instance_id": "inst_abc123",
  "timestamp": "2026-02-10T14:30:00Z",
  "data": {
    "message_id": "BAE5F2C4D3B2A1",
    "chat_id": "[email protected]",
    "from": "[email protected]",
    "type": "text",
    "text": "Hello, I need help with my order",
    "timestamp": "2026-02-10T14:30:00Z"
  }
}

{
  "id": "dlv_def456",
  "event": "message.delivered",
  "instance_id": "inst_abc123",
  "timestamp": "2026-02-10T14:30:05Z",
  "data": {
    "message_id": "BAE5A1B2C3D4E5",
    "chat_id": "[email protected]",
    "status": "delivered"
  }
}

{
  "id": "dlv_ghi789",
  "event": "message.read",
  "instance_id": "inst_abc123",
  "timestamp": "2026-02-10T14:31:00Z",
  "data": {
    "message_id": "BAE5A1B2C3D4E5",
    "chat_id": "[email protected]",
    "status": "read"
  }
}

{
  "id": "dlv_jkl012",
  "event": "message.reaction",
  "instance_id": "inst_abc123",
  "timestamp": "2026-02-10T14:32:00Z",
  "data": {
    "message_id": "BAE5F2C4D3B2A1",
    "chat_id": "[email protected]",
    "from": "[email protected]",
    "reaction": "\u2764\ufe0f"
  }
}

{
  "id": "dlv_mno345",
  "event": "instance.connected",
  "instance_id": "inst_abc123",
  "timestamp": "2026-02-10T12:00:00Z",
  "data": {
    "instance_id": "inst_abc123",
    "status": "connected",
    "phone_number": "5511999998888"
  }
}

{
  "id": "dlv_pqr678",
  "event": "instance.qr",
  "instance_id": "inst_abc123",
  "timestamp": "2026-02-10T11:59:00Z",
  "data": {
    "instance_id": "inst_abc123",
    "qr": "data:image/png;base64,iVBORw0KGgo..."
  }
}

{
  "id": "dlv_stu901",
  "event": "group.joined",
  "instance_id": "inst_abc123",
  "timestamp": "2026-02-10T15:00:00Z",
  "data": {
    "group_id": "[email protected]",
    "participant": "[email protected]"
  }
}

​
सर्वोत्तम प्रथाएं

तेजी से respond करें

5 seconds के भीतर 200 status लौटाएं। Timeouts से बचने के लिए event को asynchronously process करें।

Deduplicate करें

Retries के कारण duplicate deliveries को detect और skip करने के लिए delivery id का उपयोग करें।

Signatures verify करें

यदि आपने secret configure किया है तो हमेशा X-Wappfy-Signature header को validate करें।

HTTPS उपयोग करें

Webhook URLs को HTTPS उपयोग करना अनिवार्य है। HTTP endpoints reject कर दिए जाएंगे।