외부 연동 점검하기

옷가게 쇼핑몰 "포근한 옷장"은 새 상품을 등록하면 그 사실을 사내 알림 봇에 자동으로 알리는 Webhook(콘텐츠에 변화가 생기면 바깥 프로그램에 알림을 보내는 연동)을 설정해 두었습니다. 그런데 어느 날 담당자가 "요즘 신상품 알림이 통 안 온다"고 합니다. 알림이 정말 안 나간 것인지, 나갔는데 봇 쪽에서 놓친 것인지부터 가려야 합니다.

Webhook은 한 번 만들어 두면 알아서 도는 장치라 평소에는 신경 쓸 일이 없습니다. 하지만 알림을 받는 바깥 프로그램은 우리 손이 닿지 않는 곳에 있어서, 언젠가 응답이 없거나 오류를 돌려주는 날이 옵니다. 이 페이지는 설정해 둔 Webhook이 잘 나가고 있는지 확인하고, 실패한 호출을 찾아 원인에 따라 대응하는 방법을 상황별 레시피로 다룹니다.

Webhook이 무엇이고 어떻게 만들고 켜고 끄고 고치는지는 Webhook에서 다룹니다. 여기서는 이미 만들어 둔 Webhook을 운영하며 점검하는 쪽에 집중합니다.

호출 이력에 무엇이 남나

Webhook이 바깥 프로그램에 요청을 보낼 때마다, 그 한 번 한 번이 호출 이력에 기록으로 남습니다. 각 기록에는 다음이 담깁니다.

• 언제 보냈는지, 그리고 처리에 걸린 시간
• 어떤 변화 때문에 보냈는지 (예: 상품 등록)
• 어느 주소로 보냈는지
• 바깥 프로그램이 돌려준 응답 코드(요청을 어떻게 처리했는지 알려 주는 결과 번호)
• 그 호출이 성공이었는지 실패였는지

호출 이력은 두 층으로 되어 있습니다. 먼저 호출을 시간순으로 훑는 목록이 있고, 목록에서 한 건을 열면 그 호출의 상세가 나옵니다. 상세에서는 우리가 실제로 보낸 요청과 바깥 프로그램이 돌려준 응답을 그대로 볼 수 있습니다.

Webhook 목록에서 이름을 누르면 상세 화면이 열리고, 위쪽 Webhook 호출 탭에 이 목록이 나옵니다. "포근한 옷장"의 신상품 알림 봇이 상품이 등록될 때마다 보낸 기록은 이렇게 보입니다.

목록에는 호출 시각과 호출 결과만 간략히 보이고, 어느 주소로 무엇 때문에 보냈는지 같은 나머지 정보는 행을 눌러 상세를 열어야 보입니다. 목록이 오래돼 보이면 우측 위의 호출 새로고침으로 다시 불러올 수 있습니다.

성공과 실패는 응답 코드로 갈립니다. 응답 코드가 정상 범위(대체로 200번대·300번대)면 성공, 그 밖의 번호면 실패로 기록됩니다. 바깥 프로그램이 아예 응답하지 않았거나, 돌려준 응답이 너무 커도 그 호출은 실패로 남습니다.

알림이 잘 나가고 있는지 확인하기

담당자의 말이 맞는지 확인하려면, 먼저 이 Webhook이 지금까지 보낸 호출 중 몇 퍼센트가 성공했는지를 봅니다. Webhook 목록에 호출 성공률이 바로 보입니다.

1. 옷가게 Space의 설정에서 Webhook 화면을 여세요.
2. 목록에서 신상품 알림 봇 행의 호출 성공률(%) 칼럼을 확인하세요.

예를 들어 "66.67%"처럼 보입니다. 100%면 지금까지 보낸 호출이 모두 성공한 것이고, 그렇다면 놓친 쪽은 봇입니다. 100%보다 낮다면 알림 자체가 나가다 막힌 적이 있다는 뜻이므로, 다음 절에서 그 원인을 찾습니다.

지금까지 보낸 호출이 한 건도 없다면, 알림이 실패한 것이 아니라 아예 보내지지 않은 것입니다. Webhook이 꺼져 있거나(INACTIVE), 걸어 둔 조건에 맞는 변화가 그동안 없었을 때 그렇습니다. 이때는 Webhook에서 켜져 있는지, 어떤 변화에 반응하도록 해 뒀는지 확인하세요.

실패한 호출의 원인 찾기

실패가 보이면, 그 호출 하나를 열어 무엇이 잘못됐는지 봅니다. 상세에는 우리가 보낸 요청과 바깥 프로그램이 돌려준 응답이 함께 나옵니다.

1. 신상품 알림 봇의 Webhook 호출 탭에서 결과가 실패인 행을 누르세요. Webhook 호출 상세 화면이 열립니다.
2. 요청에서 어느 주소로, 어떤 내용을 보냈는지 확인하세요.
3. 응답에서 응답 코드와 바깥 프로그램이 돌려준 내용을 확인하세요.

응답 코드와 돌려준 내용이 원인을 알려 줍니다. 응답 코드가 실패 범위라면 바깥 프로그램이 요청은 받았지만 처리하다 실패한 것이고, 이때는 돌려준 내용에 원인이 적혀 있을 때가 많습니다. 응답이 아예 없거나 주소를 못 찾았다면, 보낼 주소가 바뀌었거나 프로그램이 내려가 있을 수 있습니다.

바깥 프로그램 담당자에게 이 호출을 그대로 전달하고 싶다면, 우측 위의 cURL 복사로 이 호출을 재현할 수 있는 형태로 복사해 보낼 수 있습니다.

보낸 요청에는 우리가 함께 보낸 헤더도 들어 있습니다. 그중 비밀값으로 지정해 둔 것(예: 바깥 프로그램에 접속할 때 쓰는 열쇠 값)은 화면에 별표로 가려져 보입니다. 원래 값은 노출되지 않으니 안심하고 상세를 확인해도 됩니다.

이 Webhook이 응답을 되돌려 채우는 WriteBack을 함께 쓴다면, 그 각 동작이 성공했는지 실패했는지도 같은 상세의 WriteBack 결과 탭에서 볼 수 있습니다. 항목별 뜻은 Webhook에서 다룹니다.

실패했을 때 대응하기

먼저 알아 둘 것이 하나 있습니다. 실패한 호출은 자동으로 다시 보내지지 않습니다. 한 번 실패한 알림은 그대로 이력에 남을 뿐, Webhook이 알아서 재전송하지 않습니다. 그래서 대응은 두 갈래로 나뉩니다. 앞으로의 알림이 정상적으로 나가도록 원인을 고치는 것, 그리고 이미 실패해 봇이 놓친 그 건을 직접 챙기는 것입니다.

상세에서 본 내용에 따라 짚어 볼 원인과 대응은 다음과 같습니다.

주소를 고치거나 Webhook을 다시 켜는 방법은 Webhook에서 다룹니다.

원인을 고쳐도, 그 사이 실패한 알림이 저절로 다시 가지는 않습니다. 실패한 호출이 각각 어떤 상품 등록이었는지는 그 호출 상세의 보낸 내용에서 확인할 수 있으니, 그 상품들에 대해서는 봇 담당자에게 직접 알려 빠진 처리를 메웁니다.

다음으로 할 일

• Webhook: Webhook이 무엇이고, 새로 만들거나 켜고 끄고 주소·조건을 수정하는 방법을 다룹니다.
• Webhook: 응답을 되돌려 채우는 WriteBack을 쓸 때, 각 동작이 어떻게 됐는지 호출 상세에서 확인하는 방법을 다룹니다.