ویب ہکس اور Zapier

جیسے ہی آپ کے ورک اسپیس میں کچھ ہوتا ہے، ویب ہکس آپ کے سرور کو ایک HTTP درخواست بھیج دیتے ہیں، جیسے کسی ایپ کا موقوف ہونا یا کسی سمارٹ لنک پر کلک ہونا۔ انہیں اپنے سسٹمز اپ ڈیٹ کرنے، Slack پر پوسٹ کرنے، یا سرور لکھے بغیر mapps.one کو Zapier، Make یا n8n سے جوڑنے کے لیے استعمال کریں۔ ویب ہکس Studio پلان پر دستیاب ہیں، فی ورک اسپیس 10 اینڈ پوائنٹس تک۔

اینڈ پوائنٹ شامل کریں

1. ڈیش بورڈ میں ڈویلپرز ← ویب ہکس کھولیں اور اینڈ پوائنٹ شامل کریں منتخب کریں۔ ورک اسپیس کے مالکان اور ایڈمنز یہ کر سکتے ہیں۔
2. ایک عوامی https URL درج کریں، بھیجے جانے والے ایونٹس (یا تمام ایونٹس) منتخب کریں اور تفصیل شامل کریں۔
3. سائننگ سیکرٹ کاپی کریں اور اسے اپنے سرور کے دیگر سیکرٹس کے ساتھ محفوظ کریں۔
4. یہ چیک کرنے کے لیے کہ آپ کا اینڈ پوائنٹ جواب دیتا ہے، ٹیسٹ ایونٹ بھیجیں منتخب کریں۔

اینڈ پوائنٹ کا صفحہ حالیہ ترسیلیں دکھاتا ہے، ہر ایک کے ساتھ رسپانس کی حیثیت، رسپانس باڈی کے پہلے 2,000 حروف اور ہر کوشش میں لگنے والا وقت۔ آپ API کے ذریعے بھی اینڈ پوائنٹس بنا اور حذف کر سکتے ہیں۔

ایونٹس

درخواست کا فارمیٹ

ہر ایونٹ JSON باڈی کے ساتھ ایک POST درخواست کے طور پر بھیجا جاتا ہے۔

باڈی ایک لفافہ ہے جس کی ساخت ہر ایونٹ کے لیے یکساں ہوتی ہے:

{
  "id": "evt_01j8c3m9t5v2x7z4b6d8f0h2k4",
  "type": "app.status_changed",
  "created_at": "2026-09-14T09:41:07+00:00",
  "workspace": {
    "id": "01j8a0f4c7d2e9h6k3m5n8q1r4",
    "name": "Habitly Labs"
  },
  "data": {
    "app": {
      "id": "01j8b2k6r3xq9v7m4n5p0s1t2w",
      "slug": "habitly",
      "name": "Habitly"
    },
    "status": "paused"
  }
}

data کا مواد ایونٹ پر منحصر ہوتا ہے۔ کسی ایپ سے متعلق ایونٹس میں ایک app آبجیکٹ شامل ہوتا ہے جس میں اس کا id، slug اور name ہوتا ہے۔

link.clicked

"data": {
  "app": { "id": "01j8b2k6r3xq9v7m4n5p0s1t2w", "slug": "habitly", "name": "Habitly" },
  "click": {
    "occurred_at": "2026-09-14 09:41:07",
    "os": "iOS",
    "device_type": "mobile",
    "country": "TR",
    "source": "instagram",
    "destination": "app_store",
    "utm_source": "instagram",
    "utm_medium": "social",
    "utm_campaign": "launch"
  }
}

occurred_at UTC میں ہوتا ہے۔ device_type کی ویلیو mobile، tablet یا desktop ہوتی ہے۔ destination کوئی اسٹور کلید، web یا landing ہوتی ہے۔ جو فیلڈز معلوم نہ ہوں وہ null ہوتی ہیں۔ بوٹ وزٹس کبھی یہ ایونٹ ٹرگر نہیں کرتے۔

app.metadata_fetched

"data": {
  "app": { "id": "01j8b2k6r3xq9v7m4n5p0s1t2w", "slug": "habitly", "name": "Habitly" },
  "source": "app_store"
}

دستخطوں کی تصدیق کریں

ہر درخواست پر دستخط چیک کریں، تاکہ آپ کو یقین ہو کہ یہ mapps.one سے آئی ہے اور راستے میں تبدیل نہیں کی گئی:

1. X-Mapps-Signature ہیڈر سے t اور v1 پڑھیں۔
2. اپنے اینڈ پوائنٹ کا سائننگ سیکرٹ استعمال کرتے ہوئے {t}.{raw request body} کا HMAC-SHA256 نکالیں، چھوٹے حروف والے hex کی شکل میں۔
3. اسے constant-time موازنے کے ذریعے v1 سے ملائیں۔
4. دوبارہ چلائی گئی درخواستوں کو روکنے کے لیے، اگر t آپ کے سرور کی گھڑی سے پانچ منٹ سے زیادہ مختلف ہو تو درخواست مسترد کر دیں۔

PHP

<?php

$secret = getenv('MAPPS_WEBHOOK_SECRET');
$body = file_get_contents('php://input');

parse_str(str_replace(',', '&', $_SERVER['HTTP_X_MAPPS_SIGNATURE'] ?? ''), $parts);

$timestamp = (int) ($parts['t'] ?? 0);
$expected = hash_hmac('sha256', $timestamp.'.'.$body, $secret);

if (! hash_equals($expected, (string) ($parts['v1'] ?? '')) || abs(time() - $timestamp) > 300) {
    http_response_code(400);
    exit;
}

$event = json_decode($body, true);

if ($event['type'] === 'link.clicked') {
    // Store $event['data']['click'] ...
}

http_response_code(200);

Laravel میں باڈی $request->getContent() سے اور ہیڈر $request->header('X-Mapps-Signature') سے پڑھیں، اور روٹ کو CSRF تحفظ سے مستثنیٰ کر دیں۔

Node.js (Express)

import crypto from 'node:crypto';
import express from 'express';

const app = express();
const secret = process.env.MAPPS_WEBHOOK_SECRET;

app.post('/webhooks/mapps', express.raw({ type: 'application/json' }), (req, res) => {
  const header = req.get('X-Mapps-Signature') ?? '';
  const parts = Object.fromEntries(header.split(',').map((pair) => pair.split('=')));
  const timestamp = Number(parts.t);
  const body = req.body.toString('utf8');

  const expected = crypto.createHmac('sha256', secret).update(`${timestamp}.${body}`).digest();
  const received = Buffer.from(parts.v1 ?? '', 'hex');
  const valid = received.length === expected.length && crypto.timingSafeEqual(received, expected);

  if (!valid || Math.abs(Date.now() / 1000 - timestamp) > 300) {
    return res.sendStatus(400);
  }

  const event = JSON.parse(body);

  if (event.type === 'link.clicked') {
    // Store event.data.click ...
  }

  res.sendStatus(200);
});

app.listen(3000);

رسپانسز اور دوبارہ کوششیں

• 10 سیکنڈ کے اندر کسی بھی 2xx حیثیت کے ساتھ جواب دیں۔ وقت لینے والا کام جواب دینے کے بعد بیک گراؤنڈ جاب میں کریں۔
• ری ڈائریکٹس کی پیروی نہیں کی جاتی، اس لیے حتمی URL استعمال کریں۔
• URL کا عوامی https ہونا ضروری ہے۔ نجی اور لوکل نیٹ ورک ایڈریسز قبول نہیں کیے جاتے۔
• اگر آپ کے اینڈ پوائنٹ کا وقت ختم ہو جائے یا وہ 2xx کے علاوہ کچھ بھی لوٹائے تو ہم مزید پانچ بار تک دوبارہ کوشش کرتے ہیں: تقریباً 1 منٹ، 5 منٹ، 30 منٹ، 2 گھنٹے اور 6 گھنٹے بعد۔ ہر کوشش کا ٹائم اسٹیمپ اور دستخط نیا ہوتا ہے۔
• ایک ہی ایونٹ ایک سے زیادہ بار پہنچ سکتا ہے، اور ایونٹس ترتیب سے ہٹ کر بھی پہنچ سکتے ہیں۔ ڈپلیکیٹس نظر انداز کرنے کے لیے X-Mapps-Delivery، یعنی ایونٹ کی id، اور انہیں ترتیب دینے کے لیے created_at استعمال کریں۔
• مسلسل 20 ناکام کوششوں کے بعد اینڈ پوائنٹ بند کر دیا جاتا ہے اور اسے مزید کچھ نہیں بھیجا جاتا۔ مسئلہ حل کریں، پھر ڈیش بورڈ میں اسے دوبارہ فعال کریں۔

Zapier، Make اور n8n

آپ سرور چلائے بغیر mapps.one کو ہزاروں ایپس سے جوڑ سکتے ہیں۔

Zapier

1. ایک Zap بنائیں جس کا ٹرگر Webhooks by Zapier ہو، اور Catch Hook منتخب کریں۔
2. Zapier کا دیا ہوا ویب ہک URL کاپی کریں۔
3. mapps.one میں اس URL کے ساتھ ایک اینڈ پوائنٹ شامل کریں اور مطلوبہ ایونٹس منتخب کریں، مثلاً app.status_changed یا analytics.daily_summary۔
4. mapps.one میں ٹیسٹ ایونٹ بھیجیں منتخب کریں، پھر Zapier میں Test trigger۔ اب پے لوڈ کی فیلڈز، جیسے data.app.name، اگلے مراحل میں استعمال کی جا سکتی ہیں۔

مثالیں: کسی ایپ کے موقوف ہونے پر Slack پیغام پوسٹ کریں، ہر دن کے کلکس Google Sheet میں شامل کریں، یا کسی کلائنٹ کے ڈومین کی تصدیق ہونے پر اسے ای میل کریں۔

Make اور n8n

Make میں Webhooks → Custom webhook ٹرگر استعمال کریں۔ n8n میں POST میتھڈ کے ساتھ Webhook نوڈ استعمال کریں۔ پھر اوپر بیان کردہ طریقے سے URL کو mapps.one میں اینڈ پوائنٹ کے طور پر شامل کریں۔

انٹیگریشن بنانا

اگر آپ دوسروں کے لیے mapps.one انٹیگریشن بنا رہے ہیں تو صارف کے کنیکٹ کرنے پر API کے ذریعے سبسکرائب کریں (POST /api/v1/webhooks)، ڈسکنیکٹ کرنے پر ان سبسکرائب کریں (DELETE /api/v1/webhooks/{id})، ایونٹ چننے والے کنٹرول کے لیے GET /api/v1/events استعمال کریں، اور کنکشن آزمانے کے لیے GET /api/v1/workspace استعمال کریں۔ API حوالہ دیکھیں۔