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의 해시값을 직접 계산하여 동일한지 확인 할 수 있습니다.

responseBody := "{\"event\":\"channel_added\",\"appId\":\"34f633c9-b012-4ca9-b453-2a4a460f464a\",\"channel\":{\"id\":\"webhook_test\",\"name\":\"webhook_test\",\"imageUrl\":\"\",\"data\":{\"test\":\"1\"},\"ownerId\":\"test1\",\"type\":\"public\",\"category\":\"categoryA\",\"subcategory\":\"subcategoryB\",\"privateTag\":\"\",\"invitationCode\":\"\",\"isFrozen\":false,\"memberCount\":1,\"maxMemberCount\":100,\"hideMessagesBeforeJoin\":false,\"members\":[{\"id\":\"test1\",\"username\":\"test1\",\"profileImageUrl\":\"\",\"disablePushNotification\":false,\"data\":{\"test\":\"1\"},\"updatedAt\":1699606163973,\"createdAt\":1697797296688,\"memberInfo\":{},\"lastReadAt\":0,\"lastSentAt\":0}],\"bannedUsers\":[],\"lastSentAt\":1699606164578,\"updatedAt\":0,\"createdAt\":1699606164578,\"mutedUsers\":[],\"pushNotificationDisabled\":false,\"pushNotificationSoundAOS\":\"\",\"pushNotificationSoundIOS\":\"\",\"privateData\":null,\"unreadCount\":0,\"lastReadAt\":0,\"lastMessage\":null}}"
apiKey := "92935b03e231483fc2cf75d9020f7e492c8fd9c7481eb4c79620ace7fe207d81"
signatureFromHeader := "i7a/Z+7iS1P6kNpnmw6P0ZSmq83LGnrtacwaffTvIdo="

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

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

const crypto = require('crypto')

const responseBody = '{"event":"channel_added","appId":"34f633c9-b012-4ca9-b453-2a4a460f464a","channel":{"id":"webhook_test","name":"webhook_test","imageUrl":"","data":{"test":"1"},"ownerId":"test1","type":"public","category":"categoryA","subcategory":"subcategoryB","privateTag":"","invitationCode":"","isFrozen":false,"memberCount":1,"maxMemberCount":100,"hideMessagesBeforeJoin":false,"members":[{"id":"test1","username":"test1","profileImageUrl":"","disablePushNotification":false,"data":{"test":"1"},"updatedAt":1699606163973,"createdAt":1697797296688,"memberInfo":{},"lastReadAt":0,"lastSentAt":0}],"bannedUsers":[],"lastSentAt":1699606164578,"updatedAt":0,"createdAt":1699606164578,"mutedUsers":[],"pushNotificationDisabled":false,"pushNotificationSoundAOS":"","pushNotificationSoundIOS":"","privateData":null,"unreadCount":0,"lastReadAt":0,"lastMessage":null}}'
const apiKey = '92935b03e231483fc2cf75d9020f7e492c8fd9c7481eb4c79620ace7fe207d81';
const signatureFromHeader = 'i7a/Z+7iS1P6kNpnmw6P0ZSmq83LGnrtacwaffTvIdo=';

const computedSignature = crypto.createHmac('sha256', apiKey).update(responseBody).digest('base64');

console.log('signatures match: ', signatureFromHeader == computedSignature);

import hmac
import hashlib
import base64

api_key = '92935b03e231483fc2cf75d9020f7e492c8fd9c7481eb4c79620ace7fe207d81'
response_body = u'{"event":"channel_added","appId":"34f633c9-b012-4ca9-b453-2a4a460f464a","channel":{"id":"webhook_test","name":"webhook_test","imageUrl":"","data":{"test":"1"},"ownerId":"test1","type":"public","category":"categoryA","subcategory":"subcategoryB","privateTag":"","invitationCode":"","isFrozen":false,"memberCount":1,"maxMemberCount":100,"hideMessagesBeforeJoin":false,"members":[{"id":"test1","username":"test1","profileImageUrl":"","disablePushNotification":false,"data":{"test":"1"},"updatedAt":1699606163973,"createdAt":1697797296688,"memberInfo":{},"lastReadAt":0,"lastSentAt":0}],"bannedUsers":[],"lastSentAt":1699606164578,"updatedAt":0,"createdAt":1699606164578,"mutedUsers":[],"pushNotificationDisabled":false,"pushNotificationSoundAOS":"","pushNotificationSoundIOS":"","privateData":null,"unreadCount":0,"lastReadAt":0,"lastMessage":null}}'
signature_from_header = 'i7a/Z+7iS1P6kNpnmw6P0ZSmq83LGnrtacwaffTvIdo='

# for python versions before v3.5.10
# digest = hmac.new(api_key,
#               msg=response_data.encode('utf-8'),
#               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=response_body.encode('utf-8'),
              digestmod=hashlib.sha256
             ).digest()
computed_signature = base64.b64encode(digest).decode()

print('signatures match: ', computed_signature == signature_from_header)

package org.example;

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Base64;

public class Main {
    public static void main(String[] args) {
        String responseBody = "{\"event\":\"channel_added\",\"appId\":\"34f633c9-b012-4ca9-b453-2a4a460f464a\",\"channel\":{\"id\":\"webhook_test\",\"name\":\"webhook_test\",\"imageUrl\":\"\",\"data\":{\"test\":\"1\"},\"ownerId\":\"test1\",\"type\":\"public\",\"category\":\"categoryA\",\"subcategory\":\"subcategoryB\",\"privateTag\":\"\",\"invitationCode\":\"\",\"isFrozen\":false,\"memberCount\":1,\"maxMemberCount\":100,\"hideMessagesBeforeJoin\":false,\"members\":[{\"id\":\"test1\",\"username\":\"test1\",\"profileImageUrl\":\"\",\"disablePushNotification\":false,\"data\":{\"test\":\"1\"},\"updatedAt\":1699606163973,\"createdAt\":1697797296688,\"memberInfo\":{},\"lastReadAt\":0,\"lastSentAt\":0}],\"bannedUsers\":[],\"lastSentAt\":1699606164578,\"updatedAt\":0,\"createdAt\":1699606164578,\"mutedUsers\":[],\"pushNotificationDisabled\":false,\"pushNotificationSoundAOS\":\"\",\"pushNotificationSoundIOS\":\"\",\"privateData\":null,\"unreadCount\":0,\"lastReadAt\":0,\"lastMessage\":null}}";
        String apiKey = "92935b03e231483fc2cf75d9020f7e492c8fd9c7481eb4c79620ace7fe207d81";
        String signatureFromHeader = "i7a/Z+7iS1P6kNpnmw6P0ZSmq83LGnrtacwaffTvIdo=";

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

            byte[] hash = hmacSha256.doFinal(responseBody.getBytes(StandardCharsets.UTF_8));
            String computedSignature = Base64.getEncoder().encodeToString(hash);

            System.out.printf("Signatures match: %b\n", signatureFromHeader.equals(computedSignature));
        } catch (NoSuchAlgorithmException | InvalidKeyException e) {
            e.printStackTrace();
        }
    }
}

Webhook Events

Event

Trigger

message

메시지 전송

message_deleted

메시지 삭제

reaction_added

메시지 리액션 추가

reaction_deleted

메시지 리액션 삭제

channel_added

채널 생성

channel_changed

채널 수정

channel_removed

채널 삭제

member_added

채널에 사용자 추가

member_left

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

member_banned

채널 사용자 차단

member_unbanned

채널 사용자 차단 해제

user_blocked

사용자 차단

user_unblocked

사용자 차단 해제

Webhook Event Payloads