Orbit 웹훅

Webhooks는 배포 상태가 변경될 때마다 서명된 HTTP POST를 선택한 URL로 보내므로, 팀이 이미 보고 있는 채널에서 빌드 실패에 대해 알 수 있습니다. 고객에게서 알게 되는 것보다 훨씬 낫습니다.

Webhooks의 위치

Orbit을 열고 프로젝트를 클릭한 다음 프로젝트 탭 스트립의 Configure 그룹 아래에서 Webhooks를 선택합니다. 이 페이지는 Webhooks라는 제목이며 배포 상태 변경 시 HTTP POST 알림을 받는다고 설명하며, Slack, Discord 및 일반 JSON을 지원합니다.

Webhook 추가

1. Add a webhook 카드에서 Label을 지정합니다. 게시하는 대상과 같은 것이 좋습니다.
2. URL을 붙여넣습니다. https://로 시작해야 합니다.
3. Trigger on 아래에서 원하는 이벤트를 선택합니다.
4. Add webhook을 클릭합니다.

서명 비밀은 생성 직후 한 번만 표시되며, 다시 표시되지 않는다는 경고가 있습니다. 다른 곳으로 이동하기 전에 복사하세요.

프로젝트는 최대 10개의 webhooks를 보유할 수 있습니다. 11번째를 추가하려고 하면 제한을 명시하는 메시지와 함께 거부됩니다.

5가지 이벤트

의도적으로 선택하세요. 바쁜 프로젝트의 모든 5개를 구독하면 유용한 경고 채널이 모두가 음소거하는 소음으로 바뀝니다. 대부분의 팀에 있어 Failed만이 올바른 시작점이며, Succeeded는 프로덕션 채널 같이 배포 알림이 실제로 유용한 경우에만 추가해야 합니다.

Slack 및 Discord

URL이 Slack 들어오는 webhook 또는 Discord webhook인 경우, Orbit이 URL에서 이를 감지하고 원본 JSON 대신 형식이 지정된 메시지를 보냅니다. 페이지는 URL 필드 아래에 이를 나타냅니다: Slack 및 Discord URL은 자동 감지됩니다.

형식이 지정된 메시지는 프로젝트 이름, 이벤트, 분기, 짧은 커밋, 빌드 시간, 배포된 URL 및 실패한 경우의 오류 텍스트를 포함합니다. 색상은 이벤트를 따르므로 채널의 빨간색 카드는 아무도 읽지 않고도 실패를 의미합니다.

다른 것은 필요하지 않습니다. Slack 또는 Discord에서 들어오는 webhook을 만들고 URL을 여기에 붙여넣은 다음 이벤트를 선택하면 완료됩니다.

일반 JSON 페이로드

다른 URL은 JSON 본문을 받습니다. 필드는 다음과 같습니다:

deliveryId을 사용하여 엔드포인트를 멱등성으로 만듭니다. 배포를 재시도하거나 네트워크 불안정으로 인해 중복이 발생한 경우, id를 사용하여 이미 처리했음을 인식할 수 있습니다.

서명 확인

모든 배포에는 3개의 헤더가 포함됩니다:

• X-Orbit-Signature-256, 서명 비밀을 사용한 정확한 요청 본문의 HMAC-SHA256이며, sha256= 다음에 16진수 다이제스트로 형식화됩니다.
• X-Orbit-Event, 이벤트 이름입니다.
• X-Orbit-Delivery, 배포 id입니다.

페이로드에 작용하기 전에 서명을 확인하세요. 원본 본문 바이트에 대해 동일한 HMAC을 계산하고 문자열 동일성보다는 상수 시간 비교를 사용하여 비교하세요.

const expected = 'sha256=' + crypto
  .createHmac('sha256', process.env.ORBIT_WEBHOOK_SECRET)
  .update(rawBody)
  .digest('hex');

if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))) {
  return res.status(401).end();
}

Webhook 테스트

각 webhook 행에는 Send test delivery가 있습니다. 실제 배포를 엔드포인트로 즉시 실행하고 받은 HTTP 코드 또는 실패 세부 정보를 보고합니다.

webhook을 추가한 직후에 사용하고 이에 의존하기 전에 사용하세요. 방화벽 규칙 또는 GET만 허용하는 경로는 사건 중에 보다 지금 훨씬 더 찾기 쉽습니다.

배포 기록

각 행에는 배포 수, 성공 백분율 및 평균 기간이 있는 지난 7일간의 스파크바, 마지막 실행 시간 및 결과가 있습니다.

개별 배포를 위해 Show delivery history를 확장하세요: 이벤트, 응답 코드, 기간 및 있었던 오류 텍스트입니다. 모든 배포는 Retry delivery로 다시 보낼 수 있으며, 받은 코드를 보고합니다.

배포는 12초 후 타임아웃됩니다. 엔드포인트가 느린 작업을 수행하는 경우, 연결을 열어 두지 말고 먼저 200으로 승인한 다음 나중에 처리하세요.

비밀 순환

Rotate secret을 클릭합니다. 새 비밀이 한 번 표시되며, 도구 설명은 이전 비밀이 즉시 무효화된다고 명시합니다.

이는 배포가 엔드포인트가 모르는 비밀로 서명되는 짧은 시간대를 의미합니다. 계획하세요: 조용한 시간에 순환하고 엔드포인트를 다음 즉시 작업으로 업데이트하세요.

비밀에 접근할 수 있는 사람이 떠날 때, 또는 공유된 채널이나 티켓에 붙여넣었을 때 순환하세요.

비활성화 및 삭제

Disable webhook은 배포를 중지하지만 구성 및 기록을 유지하며, 행에 Disabled 배지가 표시됩니다. 이는 계획된 마이그레이션 중처럼 경고를 일시 중지하는 올바른 선택입니다.

Delete webhook은 완전히 제거합니다. 확실하지 않으면 비활성화를 사용하세요.

알림을 받는 다른 방법

Webhooks는 유연한 옵션입니다. 2개의 더 가벼운 대안은 Settings에 있습니다:

• Deploy email notifications, 3가지 설정: 모든 배포, 실패만 또는 끄기.
• Notification channels, 배포 성공 또는 실패, 빌드 회귀 및 번들 회귀에 자신의 배포 기록 및 테스트 버튼과 함께 webhook URL에 게시합니다.

둘 다에 대해 Orbit Project Settings를 참조하세요.

문제 해결

배포가 HTTP 코드로 실패한 것으로 표시됩니다. 엔드포인트가 오류를 반환했습니다. 코드는 어느 것인지 알려줍니다: 404는 경로가 잘못되었다는 의미이고, 401 또는 403은 보통 자신의 서명 확인이 거부한다는 의미이며, 500은 핸들러가 던졌다는 의미입니다.

배포가 타임아웃으로 실패합니다. 엔드포인트는 12초보다 오래 걸렸습니다. 200을 즉시 반환하고 비동기적으로 작업을 수행하세요.

아무것도 배포되지 않습니다. webhook이 활성화되어 있고 예상한 이벤트가 선택되어 있는지 확인하세요. 큐에 들어가지 않은 빌드는 큐됨 이벤트를 실행하지 않습니다.

서명이 절대 검증되지 않습니다. 거의 항상 위에서 설명한 원본 바디 문제입니다. 해싱하는 정확한 바이트를 기록하고 해당 길이를 Content-Length 헤더와 비교하세요.

Slack URL이 원본 JSON으로 전송되고 있습니다. Slack 들어오는 webhooks는 hooks.slack.com 아래에 있습니다. 다른 Slack URL은 하나로 감지되지 않습니다.

다음 이동할 곳

• Triggering Deployments Via Deploy Hooks 들어오는 방향용.
• Orbit Project Settings 이메일 알림 및 알림 채널용.
• Orbit Status Page 팀뿐만 아니라 고객에게 알리기 위해.