🔔 웹훅 연동 가이드

{
  "event": "campaign_click",
  "timestamp": "2026-01-15T14:30:00+09:00",
  "delivery_id": "550e8400-e29b-41d4-a716-446655440000",
  "organization_id": 1,
  "data": {
    "campaign": {
      "id": 45,
      "name": "신년 프로모션",
      "alias": "new-year-2026",
      "short_url": "c/new-year-2026"
    },
    "url": {
      "id": 123,
      "short_url": "abc123",
      "original_url": "https://example.com/landing"
    },
    "click": {
      "ip_hash": "a1b2c3d4",
      "country": "KR",
      "browser": "Chrome",
      "os": "Android",
      "device_type": "mobile",
      "referrer": "https://example.com/page",
      "cid": "promo-123",
      "tracker_alias": "naver_blog"
    }
  }
}

{
  "event": "goal_completed",
  "timestamp": "2026-01-15T14:35:00+09:00",
  "delivery_id": "660e8400-e29b-41d4-a716-446655440000",
  "organization_id": 1,
  "data": {
    "funnel": {
      "id": 789,
      "session_id": "sess-abc-123",
      "external_user_id": "user-001",
      "current_stage": "GOAL_COMPLETED",
      "goal_type": "purchase",
      "goal_value": 29900,
      "platform": "android",
      "device_type": "mobile",
      "country_code": "KR",
      "total_duration_seconds": 185
    },
    "ip_hash": "a1b2c3d4",
    "url": {
      "id": 123,
      "short_url": "abc123",
      "original_url": "https://example.com/landing"
    },
    "campaign": {
      "id": 45,
      "name": "신년 프로모션",
      "alias": "new-year-2026"
    }
  }
}

{
  "event": "funnel_stage_changed",
  "timestamp": "2026-01-15T14:32:00+09:00",
  "delivery_id": "770e8400-e29b-41d4-a716-446655440000",
  "organization_id": 1,
  "data": {
    "stage_transition": {
      "previous_stage": "CLICKED",
      "current_stage": "APP_OPENED"
    },
    "funnel": {
      "id": 789,
      "session_id": "sess-abc-123",
      "external_user_id": "user-001",
      "platform": "ios",
      "device_type": "mobile",
      "country_code": "KR"
    }
  }
}

{
  "event": "session_event",
  "timestamp": "2026-01-15T14:33:00+09:00",
  "delivery_id": "880e8400-e29b-41d4-a716-446655440000",
  "organization_id": 1,
  "data": {
    "event": {
      "id": 456,
      "session_id": "sess-abc-123",
      "event_type": "page_view",
      "event_name": "상품 상세 페이지",
      "created_at": "2026-01-15 14:33:00"
    },
    "event_data": {
      "page_url": "https://example.com/product/123",
      "product_id": "prod-123"
    },
    "session": {
      "platform": "web",
      "last_platform": "web",
      "platform_transitions": 0,
      "total_events": 5,
      "external_user_id": "user-001"
    }
  }
}

import hmac
import hashlib

def verify_signature(payload: str, secret: str, signature_header: str) -> bool:
    expected = signature_header.replace("sha256=", "")
    actual = hmac.new(
        secret.encode("utf-8"),
        payload.encode("utf-8"),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, actual)

const crypto = require('crypto');

function verifySignature(payload, secret, signatureHeader) {
    const expected = signatureHeader.replace('sha256=', '');
    const actual = crypto
        .createHmac('sha256', secret)
        .update(payload, 'utf8')
        .digest('hex');
    return crypto.timingSafeEqual(
        Buffer.from(expected, 'hex'),
        Buffer.from(actual, 'hex')
    );
}

<?php
function verifySignature(string $payload, string $secret, string $signatureHeader): bool {
    $expected = str_replace('sha256=', '', $signatureHeader);
    $actual = hash_hmac('sha256', $payload, $secret);
    return hash_equals($expected, $actual);
}
?>

from flask import Flask, request, jsonify
import hmac
import hashlib

app = Flask(__name__)
WEBHOOK_SECRET = "your-webhook-secret"
processed_deliveries = set()  # 프로덕션에서는 Redis 사용 권장

def verify_signature(payload: bytes, secret: str, signature_header: str) -> bool:
    expected = signature_header.replace("sha256=", "")
    actual = hmac.new(
        secret.encode("utf-8"),
        payload,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, actual)

@app.route("/webhook", methods=["POST"])
def handle_webhook():
    # 1. 서명 검증
    signature = request.headers.get("X-Signature-256", "")
    if not verify_signature(request.data, WEBHOOK_SECRET, signature):
        return jsonify({"error": "Invalid signature"}), 401

    # 2. 중복 방지
    delivery_id = request.headers.get("X-Delivery-Id", "")
    if delivery_id in processed_deliveries:
        return jsonify({"status": "already processed"}), 200
    processed_deliveries.add(delivery_id)

    # 3. 이벤트 처리
    event_type = request.headers.get("X-Webhook-Event", "")
    body = request.get_json()
    data = body.get("data", {})

    handlers = {
        "click": handle_click,
        "campaign_click": handle_campaign_click,
        "goal_completed": handle_goal_completed,
        "funnel_stage_changed": handle_funnel_stage_changed,
        "session_event": handle_session_event,
    }

    handler = handlers.get(event_type)
    if handler:
        handler(data)

    return jsonify({"status": "ok"}), 200

def handle_click(data):
    url_info = data.get("url", {})
    click = data.get("click", {})
    print(f"Click: {url_info.get('short_url')} from {click.get('country')}")

def handle_campaign_click(data):
    campaign = data.get("campaign", {})
    click = data.get("click", {})
    print(f"Campaign: {campaign.get('name')}, "
          f"CID: {click.get('cid')}, Tracker: {click.get('tracker_alias')}")

def handle_goal_completed(data):
    funnel = data.get("funnel", {})
    print(f"Goal: {funnel.get('goal_type')}, Value: {funnel.get('goal_value')}")

def handle_funnel_stage_changed(data):
    transition = data.get("stage_transition", {})
    print(f"Stage: {transition.get('previous_stage')} → {transition.get('current_stage')}")

def handle_session_event(data):
    event = data.get("event", {})
    session = data.get("session", {})
    print(f"Session: {event.get('event_type')}, "
          f"Platform: {session.get('platform')}, "
          f"Transitions: {session.get('platform_transitions')}")

if __name__ == "__main__":
    app.run(port=3000)

const express = require('express');
const crypto = require('crypto');

const app = express();
const WEBHOOK_SECRET = 'your-webhook-secret';
const processedDeliveries = new Set(); // 프로덕션에서는 Redis 사용 권장

// raw body를 보존하기 위해 express.raw() 사용
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
    const payload = req.body.toString('utf8');

    // 1. 서명 검증
    const signature = req.headers['x-signature-256'] || '';
    if (!verifySignature(payload, WEBHOOK_SECRET, signature)) {
        return res.status(401).json({ error: 'Invalid signature' });
    }

    // 2. 중복 방지
    const deliveryId = req.headers['x-delivery-id'] || '';
    if (processedDeliveries.has(deliveryId)) {
        return res.json({ status: 'already processed' });
    }
    processedDeliveries.add(deliveryId);

    // 3. 빠르게 응답 후 비동기 처리
    res.json({ status: 'ok' });

    const body = JSON.parse(payload);
    const eventType = req.headers['x-webhook-event'] || '';
    const data = body.data || {};

    switch (eventType) {
        case 'click':
            console.log(`Click: ${data.url?.short_url} from ${data.click?.country}`);
            break;
        case 'campaign_click':
            console.log(`Campaign: ${data.campaign?.name}, ` +
                `CID: ${data.click?.cid}, Tracker: ${data.click?.tracker_alias}`);
            break;
        case 'goal_completed':
            console.log(`Goal: ${data.funnel?.goal_type}, Value: ${data.funnel?.goal_value}`);
            break;
        case 'funnel_stage_changed':
            console.log(`Stage: ${data.stage_transition?.previous_stage} → ` +
                `${data.stage_transition?.current_stage}`);
            break;
        case 'session_event':
            console.log(`Session: ${data.event?.event_type}, ` +
                `Platform: ${data.session?.platform}, ` +
                `Transitions: ${data.session?.platform_transitions}`);
            break;
    }
});

function verifySignature(payload, secret, signatureHeader) {
    const expected = signatureHeader.replace('sha256=', '');
    const actual = crypto
        .createHmac('sha256', secret)
        .update(payload, 'utf8')
        .digest('hex');
    try {
        return crypto.timingSafeEqual(
            Buffer.from(expected, 'hex'),
            Buffer.from(actual, 'hex')
        );
    } catch (e) {
        return false;
    }
}

app.listen(3000, () => console.log('Webhook receiver on port 3000'));

<%@ page contentType="application/json; charset=UTF-8" %>
<%@ page import="java.io.*, java.util.*, java.security.*, javax.crypto.*, javax.crypto.spec.*" %>
<%@ page import="com.google.gson.JsonObject, com.google.gson.JsonParser" %>
<%
// FingerpushLink 웹훅 수신 서버 (JSP)
// 필요: gson 라이브러리 (WEB-INF/lib/gson-x.x.x.jar)

final String WEBHOOK_SECRET = "YOUR_WEBHOOK_SECRET_HERE";

// 1. POST 메서드 확인
if (!"POST".equalsIgnoreCase(request.getMethod())) {
    response.setStatus(405);
    out.print("{\"error\": \"Method Not Allowed\"}");
    return;
}

// 2. 요청 본문 읽기
StringBuilder sb = new StringBuilder();
BufferedReader reader = request.getReader();
String line;
while ((line = reader.readLine()) != null) {
    sb.append(line);
}
String body = sb.toString();

// 3. 서명 검증
String signatureHeader = request.getHeader("X-Signature-256");
if (signatureHeader == null || signatureHeader.isEmpty()) {
    response.setStatus(401);
    out.print("{\"error\": \"Missing signature\"}");
    return;
}

String signature = signatureHeader.replace("sha256=", "");
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(WEBHOOK_SECRET.getBytes("UTF-8"), "HmacSHA256"));
byte[] hash = mac.doFinal(body.getBytes("UTF-8"));
StringBuilder hexStr = new StringBuilder();
for (byte b : hash) {
    hexStr.append(String.format("%02x", b));
}
String expected = hexStr.toString();

if (!MessageDigest.isEqual(expected.getBytes(), signature.getBytes())) {
    response.setStatus(401);
    out.print("{\"error\": \"Invalid signature\"}");
    return;
}

// 4. 중복 방지 (Delivery ID 확인)
String deliveryId = request.getHeader("X-Delivery-Id");
// 실제 프로젝트에서는 DB/Redis에 저장하여 중복 체크

// 5. 이벤트 처리
String eventType = request.getHeader("X-Webhook-Event");
JsonObject payload = JsonParser.parseString(body).getAsJsonObject();
JsonObject data = payload.getAsJsonObject("data");

switch (eventType != null ? eventType : "") {
    case "click":
        String shortUrl = data.getAsJsonObject("url").get("short_url").getAsString();
        application.log("[click] shortUrl=" + shortUrl);
        break;
    case "campaign_click":
        String alias = data.getAsJsonObject("campaign").get("alias").getAsString();
        application.log("[campaign_click] alias=" + alias);
        break;
    case "goal_completed":
        JsonObject funnel = data.getAsJsonObject("funnel");
        application.log("[goal_completed] goalType=" + funnel.get("goal_type").getAsString());
        break;
    case "session_event":
        JsonObject event = data.getAsJsonObject("event");
        application.log("[session_event] eventName=" + event.get("event_name").getAsString());
        break;
    case "funnel_stage_changed":
        JsonObject transition = data.getAsJsonObject("stage_transition");
        application.log("[funnel_stage_changed] " +
            transition.get("previous_stage").getAsString() +
            " -> " + transition.get("current_stage").getAsString());
        break;
}

// 6. 성공 응답
response.setStatus(200);
out.print("{\"status\": \"ok\", \"deliveryId\": \"" + deliveryId + "\"}");
%>

<?php
// FingerpushLink 웹훅 수신 서버 (PHP)
// PHP 7.4+ 필요, 추가 라이브러리 불필요

header('Content-Type: application/json; charset=UTF-8');

$WEBHOOK_SECRET = 'YOUR_WEBHOOK_SECRET_HERE';

// 1. POST 메서드 확인
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
    http_response_code(405);
    echo json_encode(['error' => 'Method Not Allowed']);
    exit;
}

// 2. 요청 본문 읽기
$body = file_get_contents('php://input');
if (empty($body)) {
    http_response_code(400);
    echo json_encode(['error' => 'Empty body']);
    exit;
}

// 3. 서명 검증
$signatureHeader = $_SERVER['HTTP_X_SIGNATURE_256'] ?? '';
if (empty($signatureHeader)) {
    http_response_code(401);
    echo json_encode(['error' => 'Missing signature']);
    exit;
}

$signature = str_replace('sha256=', '', $signatureHeader);
$expected = hash_hmac('sha256', $body, $WEBHOOK_SECRET);
if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    echo json_encode(['error' => 'Invalid signature']);
    exit;
}

// 4. 중복 방지 (Delivery ID 확인)
$deliveryId = $_SERVER['HTTP_X_DELIVERY_ID'] ?? '';
// 실제 프로젝트: DB/Redis에 저장 후 중복 체크

// 5. 이벤트 타입별 처리
$eventType = $_SERVER['HTTP_X_WEBHOOK_EVENT'] ?? '';
$payload = json_decode($body, true);
$data = $payload['data'];

switch ($eventType) {
    case 'click':
        $url = $data['url'];
        error_log("[클릭] shortUrl={$url['short_url']}");
        break;
    case 'campaign_click':
        $campaign = $data['campaign'];
        $click = $data['click'];
        error_log("[캠페인] alias={$campaign['alias']}, cid={$click['cid']}");
        break;
    case 'goal_completed':
        $funnel = $data['funnel'];
        error_log("[목표달성] goalType={$funnel['goal_type']}");
        break;
    case 'session_event':
        $event = $data['event'];
        error_log("[세션이벤트] eventName={$event['event_name']}");
        break;
    case 'funnel_stage_changed':
        $transition = $data['stage_transition'];
        error_log("[퍼널변경] {$transition['previous_stage']} -> {$transition['current_stage']}");
        break;
}

// 6. 성공 응답
http_response_code(200);
echo json_encode([
    'status' => 'ok',
    'deliveryId' => $deliveryId,
]);
?>