웹훅
웹훅을 사용하면 시스템이 Tuist 내부의 변경 사항이 발생하는 즉시 반응할 수 있습니다. 관련 이벤트(새 테스트 케이스 관찰, 미리보기 업로드 완료, 불안정한 테스트 수정 등)가 발생할 때마다 Tuist는 해당 이벤트 유형을 구독한 모든 엔드포인트로 HTTP POST 요청을 보냅니다. 요청 본문은 JSON envelope이며, 각 전달에는 엔드포인트의 서명 비밀 키로 검증할 수 있는 서명 헤더가 포함됩니다.
대상 URL을 등록하고 원하는 이벤트를 선택하면 Tuist가 서명, 재시도 및 전달 감사 로그를 처리합니다.
웹훅 수신 단계#
다음 단계에 따라 앱에서 이벤트 알림 수신을 시작할 수 있습니다.
- 애플리케이션이 수신하려는 이벤트를 식별합니다.
- 로컬 서버에서 HTTP 엔드포인트(URL)로 웹훅 엔드포인트를 생성합니다.
- 페이로드를 파싱하고 2xx 상태 코드를 반환하여 Tuist가 전달을 성공으로 표시하도록 Tuist의 요청을 처리합니다.
- 요청이 Tuist에서 왔음을 증명하기 위해 모든 요청의 서명을 검증합니다.
- 빌드하는 동안 디버깅하려면 Tuist 대시보드의 이벤트 로그를 사용하세요.
이벤트 유형#
Tuist는 이벤트가 설명하는 리소스별로 이벤트를 그룹화합니다. Envelope의 type 필드는 점 표기법({resource}.{action})을 사용하며, 이는 대시보드에서 구독하는 값과 동일합니다.
| Type | When it fires |
|---|---|
test_case.created |
A test case was observed for the first time in this account. |
test_case.updated |
A test case's attributes changed. |
preview.created |
A new preview was created in this account. |
preview.deleted |
A preview was deleted from this account. |
runner_job.started |
A runner started a job created through the runners API. |
runner_job.completed |
A job created through the runners API completed, failed or was cancelled. |
더 많은 이벤트 유형이 추가될 예정입니다. 아직 제공되지 않는 이벤트가 필요하면 알려주시면 카탈로그에 추가하겠습니다.
엔드포인트 생성#
엔드포인트는 계정별로 구성됩니다. 계정 설정에서 웹훅을 열고 엔드포인트 추가를 클릭한 후 다음 정보를 입력하세요.
- 이름 — 목록에서 엔드포인트가 표시되는 방식입니다.
- 엔드포인트 URL —
https://를 사용해야 합니다. - 수신할 이벤트 — 특정 이벤트를 선택하거나 그룹 수준에서 모두 선택을 사용합니다. Tuist는 구독된 이벤트 중 하나가 발생했을 때만 엔드포인트로 POST 요청을 보냅니다.

저장하면 Tuist는 새로운 서명 비밀 키를 생성하고 한 번만 표시합니다. 애플리케이션 구성에 즉시 복사하세요. 대시보드에서 다시 검색할 수 없습니다. 분실한 경우 엔드포인트 작업 메뉴에서 비밀 키 회전을 사용하여 새 키를 발급받으세요.
페이로드#
모든 전달은 단일 JSON 객체입니다. Envelope는 전달의 중복 제거, 라우팅 및 감사를 위해 사용할 수 있는 메타데이터로 이벤트별 리소스 스냅샷을 감쌉니다.
| 필드 | 설명 |
|---|---|
id |
이 전달에 고유한 UUID입니다. 재시도가 발생할 때 중복을 제거하는 데 사용하세요. |
type |
점 표기법 이벤트 유형(예: test_case.updated). |
created |
Tuist가 전달을 큐에 넣은 Unix 타임스탬프(초)입니다. |
object |
리소스 스냅샷입니다. 구조는 이벤트 유형에 따라 달라집니다. |
각 이벤트 유형의 정확한 페이로드 스키마는 Tuist API 참조의 웹훅 이벤트 섹션에 문서화되어 있습니다. 모든 이벤트에는 components.schemas 아래의 일치하는 WebhookXxxEvent 스키마가 있으며, 코드 생성기에서 $ref할 수 있습니다.
예를 들어 test_case.updated 페이로드에는 쓰기를 유발한 표준 전환(marked_flaky, muted, unskipped 등)을 나열하는 events 배열과 수신자가 수동 편집과 자동화 기반 변경 사항을 구분할 수 있도록 하는 actor_id 및 alert_id도 포함됩니다.
각 요청에는 다음 HTTP 헤더도 포함됩니다.
| 헤더 | 설명 |
|---|---|
Content-Type |
항상 application/json입니다. |
User-Agent |
Tuist-Webhooks/1.0. |
Tuist-Event-Id |
본문의 id와 동일한 UUID입니다. 페이로드를 파싱하기 전에 헤더를 로깅하는 경우 편리합니다. |
Tuist-Event-Type |
본문의 type와 동일한 문자열입니다. |
Tuist-Signature |
HMAC-SHA256 서명으로, t={timestamp},v1={hex_digest} 형식입니다. 아래를 참조하세요. |
웹훅 응답#
전달을 확인하려면 엔드포인트에서 2xx 상태 코드를 반환해야 합니다. 2xx 범위를 벗어나는 모든 응답(연결 실패 및 시간 초과 포함)은 전달 실패로 처리되어 재시도됩니다. Tuist는 3xx 응답을 따르지 않으므로 리디렉션하지 않고 정규 URL에서 직접 응답하세요.
핸들러를 빠르게 유지하세요. Tuist는 응답을 최대 10초 동안 기다립니다. 다른 API 호출, 데이터베이스 업데이트, 알림 전송 등 무거운 작업이 필요한 경우 요청을 수락하고 비동기적으로 처리하세요. 조기에 응답하면 다운스트림 서비스의 일시적인 지연에도 탄력적으로 대응할 수 있습니다.
서명 검증#
엔드포인트 URL을 아는 사람은 누구나 해당 URL로 POST 요청을 보낼 수 있습니다. 서명 비밀 키를 사용하면 Tuist에서 오지 않은 요청을 서버에서 거부할 수 있습니다.
Tuist는 모든 요청에 대해 다음을 계산합니다.
signed_payload = "{timestamp}.{raw_request_body}"
signature = HMAC-SHA256(signing_secret, signed_payload)
header = "t={timestamp},v1={hex(signature)}"
여러분 측에서 검증하는 방법:
Tuist-Signature헤더를 읽고t=(타임스탬프) 부분과v1=(16진수 다이제스트) 부분으로 분할하세요.- 타임스탬프가 서버의 현재 시간과 5분 이상 차이가 나면 요청을 거부하세요. 이는 재생 공격 창을 제한하지만 완전히 차단하지는 않으므로 아래에서 설명하는 멱등성과 함께 사용하세요.
HMAC-SHA256(signing_secret, "{timestamp}.{raw_body}")를 다시 계산하고 상수 시간에 다이제스트와 비교하세요.- 페이로드
id(Tuist-Event-Id헤더로도 노출됨)를 기준으로 전달을 중복 제거하세요. 재시도에서도 이 ID는 안정적이므로 이미 처리한 ID를 저장해 두면 허용 오차 범위 내에서 캡처된 요청이 재생되는 것을 방지하고 재시도 시 이중 처리로부터 보호할 수 있습니다.
서명은 Tuist가 보낸 바이트를 기반으로 계산됩니다. 웹 프레임워크가 검증 전에 JSON을 다시 파싱하고 직렬화하면 다이제스트가 일치하지 않습니다. 원본 바디(예: Rack의 request.body.read, Express의 원본 Buffer)를 캡처하여 검증기에 전달하세요.
Node.js용 참조 검증기입니다. 수신기가 작성된 언어에 맞게 동일한 네 단계(헤더 파싱, 타임스탬프 편차 확인, HMAC 재계산, 상수 시간 비교)를 변환하세요.
import crypto from "node:crypto";
function verifyTuistSignature(rawBody, header, secret, toleranceSeconds = 300) {
const parts = Object.fromEntries(
header.split(",").map((kv) => kv.split("=", 2))
);
const timestamp = Number(parts.t);
const signature = parts.v1;
if (!timestamp || !signature) return false;
const drift = Math.abs(Math.floor(Date.now() / 1000) - timestamp);
if (drift > toleranceSeconds) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(`${timestamp}.${rawBody}`)
.digest("hex");
const a = Buffer.from(expected, "hex");
const b = Buffer.from(signature, "hex");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
재시도#
Tuist는 non-2xx 상태를 반환하거나 시간 초과되거나 연결에 실패한 모든 전달을 재시도합니다. 일정은 고정되어 있습니다.
| 시도 횟수 | 전송 전 대기 시간 |
|---|---|
| 1 | (즉시) |
| 2 | 1분 |
| 3 | 5분 |
| 4 | 30분 |
| 5 | 2시간 |
| 6 | 8시간 |
| 7 | 24시간 |
일곱 번째 시도가 실패하면 전달은 영구적으로 실패로 표시됩니다. 모든 시도는 전송된 타임스탬프로 서명되므로 재시도 시에도 재생 공격 방지 창이 적용되며 이를 넓힐 필요가 없습니다.
전달 검사#
웹훅 페이지에서 엔드포인트를 열어 전달 기록을 확인하세요. 상세 페이지에는 다음 정보가 표시됩니다.
- 대상 URL, 마스킹된 서명 비밀 키, 구독한 이벤트 및 생성 날짜가 포함된 요약 카드
- 선택한 시간 범위를 기준으로 한 누적 합계와 실패 횟수가 표시된 전달 차트
- 상태, 이벤트 유형 또는 이벤트 ID로 필터링할 수 있는 이벤트 테이블

이벤트를 클릭하면 해당 시도의 전체 요청과 응답(Tuist가 보낸 정확한 페이로드, 헤더, 업스트림 상태 코드 및 응답 본문)을 확인할 수 있습니다. 이는 서버가 본 데이터와 동일하므로 서명 검증 불일치나 5xx 업스트림 오류를 디버깅하는 가장 빠른 방법입니다.

통합을 디버깅할 때 과거 기록을 조회할 수 있도록 전달 기록은 무기한 보관됩니다. 다운스트림 시스템에서 내구성 있는 복사본(예: 규정 준수용)이 필요한 경우 도착하는 대로 자체 인프라에서 전달을 캡처하세요.
엔드포인트 회전 또는 삭제#
두 작업 모두 엔드포인트 행의 케밥 메뉴와 엔드포인트 상세 페이지에 있습니다.
- 비밀 키 회전 — 새로운 서명 비밀 키를 생성하고 한 번만 표시합니다. 기존 소비자는 업데이트하기 전까지 검증에 실패하므로 배포와 함께 회전을 계획하세요.
- 엔드포인트 삭제 — 엔드포인트를 제거하고 전달을 중단합니다. 이미 기록된 전달 시도는 표준 보존 기간이 만료될 때까지 유지됩니다.
보안 참고 사항#
- 엔드포인트 URL은 HTTPS여야 합니다. Tuist는 평문 대상에는 전달을 거부합니다.
- Tuist는 각 전달 전에 대상 호스트 이름을 해결하며 루프백, RFC1918, 링크 로컬, ULA 및 클라우드 메타데이터 주소(
169.254.169.254,fd00::/8등)를 거부합니다. 이를 통해 잘못 구성된 웹훅이 Tuist 서버를 실행하는 호스트를 스캔하거나 공격하는 데 사용되는 것을 방지합니다. - 엔드포인트 URL과 서명 비밀 키는 저장 시 암호화됩니다. 이들은 베어러 자격 증명이므로 GDPR/CCPA 데이터 내보내기에서 제외됩니다.
- 서명 비밀 키는 한 번만 표시됩니다. 비밀번호처럼 취급하여 리포지토리가 아닌 비밀 관리자에 저장하세요.