clerk/clerk-webhooks

clerk-webhooks은(는) 무엇을 하나요?

Clerk 웹훅을 사용한 실시간 이벤트 처리 및 데이터 동기화. 프레임워크별 패키지의 verifyWebhook으로 검증합니다. 사용자, 세션, 조직, 결제 이벤트를 처리합니다. 데이터베이스 동기화, 알림, 통합 등 이벤트 기반 기능을 구축합니다.

개요

Clerk 웹훅은 사용자 인증, 세션, 조직, 결제와 관련된 실시간 이벤트를 애플리케이션에 전달합니다. 이를 통해 Clerk의 이벤트를 수신하고 데이터베이스 동기화, 알림 전송, 외부 시스템과의 통합 등 다양한 작업을 수행할 수 있습니다.

지원되는 웹훅 이벤트

다음은 주요 웹훅 이벤트 목록입니다:

• user.created - 새 사용자가 생성됨
• user.updated - 사용자 정보가 업데이트됨
• user.deleted - 사용자가 삭제됨
• session.created - 새 세션이 생성됨
• session.ended - 세션이 종료됨
• organization.created - 조직 생성됨
• organization.updated - 조직 정보 업데이트됨
• organization.deleted - 조직 삭제됨
• organizationMembership.created - 조직 멤버십 추가됨
• organizationMembership.deleted - 조직 멤버십 제거됨
• billing.* - 구독 및 결제 관련 이벤트

설치 및 설정

1. Clerk SDK 설치

선택한 프레임워크에 따라 적절한 Clerk 패키지를 설치합니다:

npm install @clerk/nextjs
# 또는
npm install @clerk/express
# 또는
npm install @clerk/fastify

2. 웹훅 엔드포인트 생성

Next.js App Router 예시

import { Webhook } from 'svix'
import { headers } from 'next/headers'
import { WebhookEvent } from '@clerk/nextjs/server'

export async function POST(req: Request) {
  const WEBHOOK_SECRET = process.env.CLERK_WEBHOOK_SECRET
  
  if (!WEBHOOK_SECRET) {
    throw new Error('Please add CLERK_WEBHOOK_SECRET from Clerk Dashboard to .env or .env.local')
  }

  // 헤더 가져오기
  const headerPayload = headers()
  const svixId = headerPayload.get('svix-id')
  const svixTimestamp = headerPayload.get('svix-timestamp')
  const svixSignature = headerPayload.get('svix-signature')

  if (!svixId || !svixTimestamp || !svixSignature) {
    return new Response('Error occurred -- no svix headers', {
      status: 400
    })
  }

  // 본문 가져오기
  const payload = await req.json()
  const body = JSON.stringify(payload)

  // Svix 웹훅 검증 객체 생성
  const wh = new Webhook(WEBHOOK_SECRET)
  
  let evt: WebhookEvent

  // 페이로드 검증
  try {
    evt = wh.verify(body, {
      'svix-id': svixId,
      'svix-timestamp': svixTimestamp,
      'svix-signature': svixSignature,
    }) as WebhookEvent
  } catch (err) {
    console.error('Error verifying webhook:', err)
    return new Response('Error occurred', {
      status: 400
    })
  }

  // 이벤트 타입에 따른 처리
  const { type } = evt
  
  switch (type) {
    case 'user.created':
      // 사용자 생성 시 처리 로직
      break
    case 'user.updated':
      // 사용자 업데이트 처리 로직
      break
    case 'user.deleted':
      // 사용자 삭제 처리 로직
      break
    default:
      console.log(`처리되지 않은 이벤트 타입: ${type}`)
  }

  return new Response('Webhook received', { status: 200 })
}

환경 변수 설정

.env.local 파일에 Clerk 웹훅 시크릿을 추가하세요:

CLERK_WEBHOOK_SECRET=whsec_your_webhook_secret

보안 고려사항

• 항상 웹훅 페이로드를 검증하세요. verifyWebhook을 사용하면 자동으로 처리됩니다.
• 웹훅 시크릿은 환경 변수로 안전하게 관리하세요.
• HTTPS 엔드포인트를 사용하세요.
• 이벤트 처리는 멱등성(idempotency)을 보장하도록 설계하세요.

모범 사례

1. 데이터베이스 동기화: 사용자 정보를 로컬 데이터베이스와 동기화할 때 웹훅을 사용하세요.
2. 비동기 처리: 시간이 오래 걸리는 작업은 큐 시스템을 사용하여 처리하세요.
3. 에러 처리: 웹훅 처리 실패 시 적절한 로깅과 재시도 메커니즘을 구현하세요.
4. 테스트: Clerk Dashboard에서 웹훅 테스트를 통해 엔드포인트를 검증하세요.

추가 자료

• Clerk Webhooks 문서
• Svix Webhooks 문서
• Clerk 이벤트 참조