Geliştiriciler

Webhook'lar ve Zapier

Webhook'lar, çalışma alanında bir şey olduğu anda, örneğin bir uygulama duraklatıldığında ya da bir akıllı bağlantı tıklandığında, sunucuna bir HTTP isteği gönderir. Bunları kendi sistemlerini güncellemek, Slack'e mesaj göndermek ya da sunucu yazmadan mapps.one'ı Zapier, Make veya n8n'e bağlamak için kullanabilirsin. Webhook'lar Studio planında, çalışma alanı başına en fazla 10 uç noktayla kullanılabilir.

Uç nokta ekleme

Panelde Geliştiriciler → Webhook'lar bölümünü aç ve Uç nokta ekle'yi seç. Bunu çalışma alanı sahipleri ve yöneticileri yapabilir.
Herkese açık bir https adresi yaz, gönderilecek olayları (ya da tüm olayları) seç ve bir açıklama ekle.
İmzalama anahtarını kopyala ve sunucunun diğer gizli anahtarlarıyla birlikte sakla.
Uç noktanın yanıt verdiğini kontrol etmek için Test olayı gönder düğmesini seç.

Uç nokta sayfası son gönderimleri; yanıt durumu, yanıt gövdesinin ilk 2.000 karakteri ve her denemenin ne kadar sürdüğüyle birlikte gösterir. Uç noktaları API ile de oluşturup silebilirsin.

Olaylar

Tür	Ne zaman gönderilir
`app.created`	Çalışma alanına bir uygulama eklendiğinde.
`app.updated`	Uygulama bilgileri, bağlantıları ya da sayfa ayarları değiştiğinde.
`app.deleted`	Bir uygulama silindiğinde.
`app.status_changed`	Bir uygulama yayına alındığında, duraklatıldığında ya da askıya alındığında.
`app.metadata_fetched`	Bir uygulama için mağaza bilgileri içe aktarıldığında.
`legal.published`	Bir gizlilik politikası ya da kullanım koşulları belgesi yayınlandığında.
`domain.verified`	Bir özel alan adı doğrulandığında.
`link.clicked`	Her akıllı bağlantı tıklamasında. Popüler bir uygulamada çok sayıda istek anlamına gelebilir.
`analytics.daily_summary`	Her uygulamanın bir önceki güne ait tıklama toplamları, günde bir kez.

İstek biçimi

Her olay, JSON gövdeli bir POST isteği olarak gönderilir.

Başlık	Değer
`Content-Type`	`application/json`
`User-Agent`	`mapps.one-Webhooks/1.0`
`X-Mapps-Event`	`link.clicked` gibi olay türü
`X-Mapps-Delivery`	Olay kimliği. Her yeniden denemede aynı kalır.
`X-Mapps-Timestamp`	Bu gönderim denemesinin Unix zamanı
`X-Mapps-Signature`	`t={zaman damgası},v1={imza}`

Gövde, her olay için aynı yapıya sahip bir zarftır:

{
  "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 içeriği olaya göre değişir. Bir uygulamayla ilgili olaylar, id, slug ve name içeren bir app nesnesi barındırır.

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'dir. device_type değeri mobile, tablet ya da desktop olur. destination bir mağaza anahtarı, web ya da landing olur. Bilinmeyen alanlar null olur. Bot ziyaretleri bu olayı hiçbir zaman tetiklemez.

app.metadata_fetched

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

İmzaları doğrulama

İsteğin mapps.one'dan geldiğini ve yolda değiştirilmediğini bilmek için her istekte imzayı kontrol et:

X-Mapps-Signature başlığından t ve v1 değerlerini oku.
Uç noktanın imzalama anahtarıyla {t}.{ham istek gövdesi} değerinin HMAC-SHA256 özetini küçük harfli hex olarak hesapla.
Sonucu sabit süreli bir karşılaştırmayla v1 ile karşılaştır.
Tekrar gönderilen istekleri engellemek için t sunucunun saatinden beş dakikadan fazla farklıysa isteği reddet.

Ham gövdeyi kullan. JSON'u ayrıştırmadan önce, aldığın baytların aynısını imzala. JSON'u yeniden kodlamak eğik çizgileri ya da Unicode karakterleri değiştirip imzayı bozabilir.

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') {
    // $event['data']['click'] verisini kaydet ...
}

http_response_code(200);

Laravel'de gövdeyi $request->getContent(), başlığı $request->header('X-Mapps-Signature') ile oku ve rotayı CSRF korumasının dışında tut.

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') {
    // event.data.click verisini kaydet ...
  }

  res.sendStatus(200);
});

app.listen(3000);

Yanıtlar ve yeniden denemeler

10 saniye içinde herhangi bir 2xx durumuyla yanıt ver. Uzun süren işleri yanıt verdikten sonra bir arka plan işinde yap.
Yönlendirmeler izlenmez; son adresi kullan.
Adres herkese açık bir https adresi olmalı. Özel ve yerel ağ adresleri reddedilir.
Uç noktan zaman aşımına uğrarsa ya da 2xx dışında bir yanıt döndürürse en fazla beş kez daha deneriz: yaklaşık 1 dakika, 5 dakika, 30 dakika, 2 saat ve 6 saat sonra. Her denemenin yeni bir zaman damgası ve imzası olur.
Aynı olay birden fazla kez gelebilir ve olaylar sırasız gelebilir. Tekrarları ayıklamak için olayın id değeriyle aynı olan X-Mapps-Delivery başlığını, sıralamak için created_at değerini kullan.
Arka arkaya 20 başarısız denemeden sonra uç nokta kapatılır ve ona başka bir şey gönderilmez. Sorunu gider, ardından uç noktayı panelden yeniden aç.

Zapier, Make ve n8n

mapps.one'ı sunucu çalıştırmadan binlerce uygulamaya bağlayabilirsin.

Zapier

Tetikleyici olarak Webhooks by Zapier seçip Catch Hook ile bir Zap oluştur.
Zapier'in verdiği webhook adresini kopyala.
mapps.one'da bu adresle bir uç nokta ekle ve istediğin olayları seç, örneğin app.status_changed ya da analytics.daily_summary.
mapps.one'da Test olayı gönder düğmesini, ardından Zapier'de Test trigger'ı seç. Artık data.app.name gibi alanları sonraki adımlarda kullanabilirsin.

Örnekler: bir uygulama duraklatıldığında Slack'e mesaj gönder, her günün tıklamalarını bir Google E-Tablosu'na ekle ya da bir müşterinin alan adı doğrulandığında ona e-posta gönder.

Make ve n8n

Make'te Webhooks → Custom webhook tetikleyicisini kullan. n8n'de POST yöntemiyle Webhook düğümünü kullan. Ardından yukarıdaki gibi adresi mapps.one'da uç nokta olarak ekle.

Entegrasyon geliştirme

Başkaları için bir mapps.one entegrasyonu geliştiriyorsan, kullanıcı bağlandığında API ile abone ol (POST /api/v1/webhooks), bağlantıyı kestiğinde aboneliği sil (DELETE /api/v1/webhooks/{id}), olay seçici için GET /api/v1/events, bağlantıyı test etmek için GET /api/v1/workspace kullan. Ayrıntılar API başvurusunda.