웹훅 - Swipelux

비동기 변경에 대응하려면 웹훅을 사용하세요. 전달은 최소 한 번 이뤄지므로 중복, 지연, 순서가 뒤바뀐 이벤트는 정상이에요.

필요한 이벤트만 등록

POST /v3/webhooks로 엔드포인트를 생성하세요. 통합을 이끄는 문서화된 이벤트만 구독하세요. 이 예시는 transfer.state_changed를 사용해요.

Create webhook endpoint

export API_BASE='https://platform.swipelux.com'
export SWIPELUX_API_KEY='replace-with-your-api-key'

curl --request POST \
  "${API_BASE}/v3/webhooks" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}" \
  --header "Idempotency-Key: webhook-endpoint-001" \
  --header "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "url": "https://example.com/webhooks/swipelux",
  "events": ["transfer.state_changed"]
}
JSON

응답 data.id를 WEBHOOK_ID로 저장하세요. webhooks:write 권한이 있는 API 키로 GET /v3/webhooks/portal에서 포털 URL을 요청하고, 이 엔드포인트의 서명 시크릿을 가져와 API 키와 별도로 시크릿 매니저에 저장하세요. 포털 URL은 그 자체로 접근 권한을 부여하며 1시간 후 만료되므로, 매번 새 URL을 요청하고 저장하거나 공유하지 마세요. 포털은 v3 이벤트를 리소스별로 그룹화해요: Customers, Capabilities, Accounts, Recipients, Transfers, API. 각 이벤트에는 페이로드 스키마와 예시가 표시돼요. 레거시 이벤트는 지원 중단으로 표시되며 별도의 Legacy 그룹에 나열돼요. 엔드포인트가 이미 레거시 이벤트를 구독하고 있다면 계속 수신해요. 새 구독에는 v3 이벤트 이름을 선택하세요.

엔드포인트 이벤트 변경

GET /v3/webhooks/{webhookId}로 엔드포인트 하나를 조회하세요. 응답은 GET /v3/webhooks와 같은 events 형태예요. 서명 시크릿은 절대 포함되지 않아요. 조회에는 webhooks:read가 필요하며, 알 수 없는 엔드포인트 ID에는 404 not_found를 반환해요. PATCH /v3/webhooks/{webhookId}로 엔드포인트를 업데이트하세요. Idempotency-Key 헤더를 보내세요. 업데이트에는 webhooks:write가 필요해요.

현재 URL을 유지하려면 events만 보내세요.
현재 이벤트 선택을 유지하려면 url만 보내세요.
events는 선택 전체를 교체해요. 먼저 엔드포인트를 조회하고 여전히 필요한 모든 이벤트를 포함하세요.
새 구독은 v3 이벤트 이름을 사용해야 해요.
엔드포인트가 이미 구독 중인 레거시 이벤트 이름은 유지할 수 있어요. 새 레거시 이름을 추가하면 400 validation_error가 반환돼요.

이 본문은 URL을 유지하고 선택을 교체해요:

Request body

{
  "events": ["transfer.state_changed", "capability.status_changed"]
}

파싱 전에 검증

Swipelux는 새 웹훅 통합을 Svix를 통해 전달해요. 원시 요청 본문을 엔드포인트 서명 시크릿과 다음 헤더로 검증하세요:

svix-id
svix-timestamp
svix-signature

검증이 성공하기 전에 JSON을 파싱하거나 부작용을 일으키지 마세요.

Verify signature

import { Webhook } from "svix";

const verifier = new Webhook(process.env.SWIPELUX_WEBHOOK_SECRET);

export async function handleSwipeluxWebhook(request) {
  const rawBody = await request.text();
  const event = verifier.verify(rawBody, {
    "svix-id": request.headers.get("svix-id"),
    "svix-timestamp": request.headers.get("svix-timestamp"),
    "svix-signature": request.headers.get("svix-signature"),
  });

  await webhookInbox.insertIfAbsent({
    id: event.id,
    payload: event,
    status: "pending",
  });

  return new Response(null, { status: 204 });
}

서명이 없거나 유효하지 않은 요청은 거부하세요. 검증이 완료될 때까지 원시 본문을 사용 가능하게 유지하세요.

저장하고, 확인한 뒤, 처리하세요

봉투 id에 고유성 제약을 두세요. 검증된 봉투를 저장하고, 즉시 2xx를 반환한 뒤, 비동기로 처리하세요. 이벤트 ID가 이미 존재하면 완료된 부작용을 반복하지 않고 전달을 확인하세요. 대기 중이거나 실패한 로컬 작업은 자체 재시도 큐를 통해 재개하세요. 봉투 attempt 필드를 중복 제거 키나 전송 재시도 카운터로 사용하지 마세요.

현재 상태 다시 조회

웹훅 순서는 권위 있는 리소스 히스토리가 아니에요. resource.type과 resource.id를 사용해 객체를 찾고, 시스템을 업데이트하기 전에 현재 상태를 가져오세요. 전송 이벤트의 경우 GET /v3/transfers/{transferId}를 호출하세요:

Refetch transfer

curl --request GET \
  "${API_BASE}/v3/transfers/${TRANSFER_ID}" \
  --header "X-API-Key: ${SWIPELUX_API_KEY}"

고객에게 표시되는 상태와 후속 조치는 현재 API 응답에서 이끌어내세요. 두 워커가 관련 이벤트를 다른 순서로 처리해도 안전하도록 부작용을 설계하세요.

전달 복구

GET /v3/webhooks/portal을 사용해 전달 로그를 열어요. webhooks:write가 있으면 실패한 전달을 재시도하거나 수동 재생을 시작할 수도 있어요. webhooks:read만 있는 키로 연 포털은 전달 내역을 보여 주지만 재시도, 재생, 서명 시크릿 표시는 할 수 없어요. 모든 재생은 동일한 서명 검증과 지속 가능한 인박스를 거쳐야 해요. 다운타임 후 복구하려면 영향받은 창을 재생하고 참조된 각 리소스를 다시 조회하세요. 완료된 이벤트 ID는 no-op으로 남고, 미완료 레코드는 비동기로 재개돼요. 다음으로, 샌드박스에서 중복 및 순서가 뒤바뀐 전달을 검증한 뒤 프로덕션 전환 체크리스트를 완료하세요.

시작하기

고객 온보딩

자금 흐름 구축

출시

웹훅

필요한 이벤트만 등록

엔드포인트 이벤트 변경

파싱 전에 검증

저장하고, 확인한 뒤, 처리하세요

현재 상태 다시 조회

전달 복구

​필요한 이벤트만 등록

​엔드포인트 이벤트 변경

​파싱 전에 검증

​저장하고, 확인한 뒤, 처리하세요

​현재 상태 다시 조회

​전달 복구

필요한 이벤트만 등록

엔드포인트 이벤트 변경

파싱 전에 검증

저장하고, 확인한 뒤, 처리하세요

현재 상태 다시 조회

전달 복구