Webhook이란?
웹훅(Webhook)이란 잔디에 잔디가 정한 포맷에 일치하는 데이터를 수신하여 지정된 대화에 메시지 형태로 전송해주는 기능을 말합니다. 현재 잔디 커넥트에서 지원하지 않고 있는 서비스라도 해당 서비스에서 웹훅 발신(Outgoing Webhook)을 지원하는 경우, 잔디와 연동하여 변동 사항에 대해 메시지를 수신할 수 있습니다.
* Tip : 개발자 또는 IT 부서 직원의 도움을 받는다면 좀 더 쉽게 설정하실 수 있습니다.
STEP 1
잔디에서 생성된 Webhook URL 로 메시지로 수신하고 싶은 정보(HTTP POST request)를 전송해주시면 됩니다.
request에는 반드시 Accept와 Content-Type을 다음과 같이 지정해줘야 합니다.
Accept: application/vnd.tosslab.jandi-v2+json
Content-Type: application/json
참고 : 잔디 웹훅은 restful API로 동작하기 때문에 http method를 POST로 지정하셔야 합니다. 다른 method로 발송할 경우 작동하지 않습니다.
STEP 2
POST request의 포맷은 다음과 같습니다.
{
"body" : "[[PizzaHouse]](http://url_to_text) You have a new Pizza order.",
"connectColor" : "#FAC11B",
"connectInfo" : [{
"title" : "Topping",
"description" : "Pepperoni"
},
{
"title": "Location",
"description": "Empire State Building, 5th Ave, New York",
"imageUrl": "http://url_to_text"
}]
}
각 필드의 역할은 다음과 같습니다:
"body" : 일반적인 메시지의 내용입니다. 잔디에서 메시지를 작성하시고 전송하시면 보게 되는 뷰로 수신됩니다.
"connectColor" : 위의 샘플 메시지에서 본문 메시지 하단의 별도 영역으로 구분되는, 첨부 영역 부분의 컬러값을 Hex code로 지정해주실 수 있습니다.
"connectInfo" : 위의 샘플 메시지에서 첨부 영역에 어떤 내용이 들어갈지를 정의해주는 부분입니다.
"title" : 첨부 영역의 제목이며, 기본적으로 볼드체로 표시됩니다.
"description" : 첨부 영역의 상세 내용입니다. 위의 예시와 같이 Title과 Description은 메시지 구조에 따라 여러 개를 추가할 수 있습니다.
"imageUrl" : 해당 웹훅 메시지에 첨부된 이미지 파일이 있을 경우, url로 넣어주시면 이미지와 함께 웹훅을 받아보실수 있습니다.
다음은 curl request의 샘플입니다. 터미널 등의 커맨드 라인 환경(CLI)에서 실행할 경우 잔디에서 실제 메시지를 수신하는 것을 보실 수 있습니다.
단, 테스트 전 아래의 https://wh.jandi.com/connect-api/webhook/생성한-웹훅-주소 부분을 실제로 잔디에서 생성하신 웹훅의 주소로 대체하는 것을 잊지마세요.
curl \
-X POST https://wh.jandi.com/connect-api/webhook/생성한-웹훅-주소 \
-H "Accept: application/vnd.tosslab.jandi-v2+json" \
-H "Content-Type: application/json" \
--data-binary '{"body":"[[PizzaHouse]](http://url_to_text) You have a new Pizza order.","connectColor":"#FAC11B","connectInfo":[{"title":"Topping","description":"Pepperoni"},
{"title":"Location","description":"Empire State Building, 5th Ave, New York","imageUrl":"Url_to_text"}]}'
이렇게 수신된 메시지는 해당 웹훅을 생성한 대화에 다음과 같이 전송될 것입니다.
프로필 이미지와 이름 변경을 원하실 경우 잔디 커넥트 수정 화면에서 바로 수정이 가능합니다.
Tip!
고객님께서 사용하시는 서비스들 중, 웹훅을 지원하는 서비스가 있다고 하더라도 해당 서비스에서 발생하는 이벤트를 잔디가 메시지로 구성할 수 있는 포맷으로 매 번 전환해줘야만 정상적인 수신이 가능합니다. 이 역할을 하는 프로세스를 직접 개발을 할 수도 있으나, Zapier와 같은 서드파티 서비스를 통해 설정 또한 가능합니다.
잔디에서 표시할 수 있는 메시지의 최대글자수는 5000자이고, 웹훅으로 수신할 수 있는 최대 데이터 용량은 256kb입니다. 256kb는 26만 글자가 넘는 크기로서 일반적으로 사용하기에는 충분한 숫자이지만, 그 이상의 데이터를 수신하게 되면 에러 메시지를 반환합니다. 구체적으로는,
25만 글자 정도의 메시지를 웹훅으로 발송했을 때, 5000자까지만 표시됩니다.
만약 27만 글자를 발송한다면 메시지 자체를 발생하지 않게 됩니다.
[webhook 오류코드]
code | message |
40000 | 잘못된 webhook Token 형식 |
40000 | 유효하지 않은 webhook ( 비활성화 되거나 삭제된 webhook ) |
40000 | 요청 데이터의 형식이 잘못된 경우 |
42900 | Too Many Requests ( 너무 많이 요청한 경우 ) |
99. Limit
- 60 requests / min
- 500 requests / 10 min
- 제한에 걸렸을 경우 응답코드: 429
더 궁금한 점이 있으시면 잔디 고객센터 이메일(support@tosslab.com)으로 연락 주시기 바랍니다.