Webhooks

설정

TalkPlus 대시보드에서 다음과 같이 webhook 설정을 할 수 있습니다:

Webhook 기능 활성화
이벤트 트리거 대상 endpoint 입력
Webhook를 트리거할 이벤트 선택

Endpoint

HTTP POST request를 받을 수 있어야 합니다.
JSON 형태의 이벤트 데이터를 처리할 수 있어야 합니다.

TalkPlus 서버에서 endpoint를 호출하고 응답이 없을 시, 5초 이후 1회 재시도 합니다.

Header

TalkPlus에서는 다음 헤더 값을 가지고 endpoint를 호출합니다.

User-Agent

TalkPlus

content-type

application/json

x-talkplus-signature

payload를 App API Key로 sign하고(SHA-256) 결과값을 base64로 인코딩한 값

Verification

TalkPlus서버에서 보낸 request 진위여부를 확인하기 위해, request header의 x-talkplus-signature 값과 response body의 해시값을 직접 계산하여 동일한지 확인 할 수 있습니다.

package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/base64"
	"fmt"
	"io"
	"net/http"
)

const apiKey = "<your-api-key>"

func main() {
	http.HandleFunc("/webhook", func(w http.ResponseWriter, r *http.Request) {
		signatureFromHeader := r.Header.Get("X-TalkPlus-Signature")

		responseBody, err := io.ReadAll(r.Body)
		if err != nil {
			http.Error(w, "failed to read body", http.StatusBadRequest)
			return
		}

		hash := hmac.New(sha256.New, []byte(apiKey))
		hash.Write(responseBody)
		computedSignature := base64.StdEncoding.EncodeToString(hash.Sum(nil))

		fmt.Printf("signatures match: %v\n", signatureFromHeader == computedSignature)

		w.WriteHeader(http.StatusOK)
		w.Write([]byte("OK"))
	})

	http.ListenAndServe(":8080", nil)
}

const express = require("express");
const crypto = require("crypto");
const app = express();
const apiKey = '<your-api-key>';

app.use((req, res, next) => {
  let data = '';
  req.setEncoding('utf8');
  req.on('data', chunk => { data += chunk });
  req.on('end', () => {
    req.rawBody = data;
    next();
  });
});

app.post("/webhook", async (req, res) => {
  const signatureFromHeader = req.headers['x-talkplus-signature'];
  const computedSignature = crypto.createHmac('sha256', apiKey).update(req.rawBody).digest('base64');
  console.log('signatures match: ', signatureFromHeader == computedSignature);

  res.send("OK");
});

app.listen(8080);

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

app = Flask(__name__)
api_key = "<your-api-key>"

@app.route("/webhook", methods=["POST"])
def webhook():
    signature_from_header = request.headers.get("X-TalkPlus-Signature")
    raw_payload = request.get_data()

    # for python versions before v3.5.10
    # digest = hmac.new(
    #     api_key,
    #     msg=raw_payload,
    #     digestmod=hashlib.sha256
    # ).digest()

    # for python v3.5.10+,
    # hmac.new function requires key to be bytes or bytearray object
    digest = hmac.new(
        api_key.encode('ascii'),
        msg=raw_payload,
        digestmod=hashlib.sha256
    ).digest()
    computed_signature = base64.b64encode(digest).decode()
    print('signatures match: ', computed_signature == signature_from_header)
    
    return "OK", 200

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

package com.example.java;

import jakarta.servlet.http.HttpServlet;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.util.Base64;

@RestController
public class WebhookController extends HttpServlet {

    private final String apiKey = "<your-api-key>";

    @PostMapping("/webhook")
    public String handleWebhook(HttpServletRequest request, HttpServletResponse response) throws IOException {
        String signatureFromHeader = request.getHeader("X-TalkPlus-Signature");
        byte[] body = request.getInputStream().readAllBytes();

        try {
            Mac hmacSha256 = Mac.getInstance("HmacSHA256");
            SecretKeySpec secretKey = new SecretKeySpec(apiKey.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
            hmacSha256.init(secretKey);

            byte[] hash = hmacSha256.doFinal(body);
            String computedSignature = Base64.getEncoder().encodeToString(hash);

            System.out.printf("signatures match: %b\n", signatureFromHeader.equals(computedSignature));
        } catch (Exception e) {
            e.printStackTrace();
        }

        return "OK";
    }
}

Webhook Events

Event

Trigger

message

메시지 전송

message_deleted

메시지 삭제

reaction_added

메시지 리액션 추가

reaction_deleted

메시지 리액션 삭제

channel_added

채널 생성

channel_changed

채널 수정

channel_removed

채널 삭제

member_added

채널에 사용자 추가

member_left

채널에서 사용자 나감 또는 제외됨

member_muted

채널에서 사용자 mute 처리

member_unmuted

채널에서 사용자 mute 해제

member_banned

채널 사용자 차단

member_unbanned

채널 사용자 차단 해제

user_blocked

사용자 차단

user_unblocked

사용자 차단 해제

Webhook Event Payloads