SMS 인증, 꼭 서류가 필요할까요?

Next.js로 사이드 프로젝트나 MVP를 개발할 때 가장 많이 선택하는 인증 솔루션 중 하나가 바로 Clerk입니다. 소셜 로그인과 이메일 인증은 몇 번의 클릭만으로 손쉽게 연동되죠. 하지만 한국 유저를 타겟으로 **SMS 기반의 전화번호 로그인(Phone number login)**을 도입하려고 하면 예상치 못한 거대한 벽에 부딪히게 됩니다.

국내 기존 SMS API 제공업체들을 찾아보면 다음과 같은 요구사항을 마주하게 됩니다.

• 사업자등록증명원 제출
• 통신 서비스 가입 증명원 제출
• 발신번호 사전등록 (심사 대기 1~3일 소요)

나는 그저 이번 주말 동안 빠르게 토이 프로젝트를 완성하고 싶은 1인 개발자인데, 서류 준비와 심사 대기에만 며칠을 허비해야 하는 상황. 정말 서류 없이 바로 시작할 수 있는 방법은 없는 걸까요?

솔루션: Clerk SMS Webhook + EasyAuth(이지어스)

결론부터 말씀드리면, 단 5분 만에, 어떠한 서류 제출도 없이 완벽한 Next.js SMS 인증을 구현할 수 있습니다.

비결은 Clerk의 'Custom SMS Webhook' 기능과 개발자를 위한 초간단 SMS API인 **EasyAuth(이지어스)**를 결합하는 것입니다. Clerk은 사용자의 전화번호를 받아 인증번호(OTP)를 생성하고 검증하는 로직을 모두 담당하며, 실제 문자를 발송하는 역할만 웹훅을 통해 우리 서버로 위임합니다. 이때 이지어스의 API를 호출하면 모든 과정이 끝납니다.

이지어스(EasyAuth)를 선택해야 하는 이유

• 서류 불필요: 사업자등록증, 이용증명원 등 번거로운 서류 제출이 일절 없습니다.
• 즉시 시작: 가입 후 발급받은 API Key로 5분 안에 연동을 완료할 수 있습니다.
• 자동 발신번호: 대표번호 사전등록 없이 바로 문자를 발송할 수 있습니다.
• 합리적 가격: 건당 15~25원으로 기존(30~50원) 대비 훨씬 저렴하며, 가입 시 10건을 무료로 제공합니다.

---

단계별 구현 가이드

Step 1. Clerk 대시보드에서 Webhook 설정하기

먼저 Clerk이 인증번호를 생성했을 때 우리의 Next.js 서버로 알려주도록 설정해야 합니다.

1. Clerk Dashboard에 접속하여 [Integrations] 또는 [Webhooks] 메뉴로 이동합니다.
2. Add Endpoint를 클릭합니다.
3. Endpoint URL에 https://여러분의도메인.com/api/webhooks/clerk-sms를 입력합니다. (로컬 테스트 시 ngrok 등을 활용하세요)
4. Message Filtering에서 sms.created 이벤트만 체크합니다.
5. 생성된 웹훅의 Signing Secret을 복사하여 .env.local 파일에 저장합니다.

CLERK_WEBHOOK_SECRET=whsec_여러분들의_시크릿키
EASYAUTH_API_KEY=ea_여러분들의_이지어스_API키

Step 2. Next.js 웹훅 수신 API 라우트 작성

Next.js App Router를 기준으로 app/api/webhooks/clerk-sms/route.ts 파일을 생성합니다. 웹훅의 보안을 위해 Svix 패키지를 사용하여 서명을 검증해야 합니다.

npm install svix

웹훅 라우트는 Clerk으로부터 phone_number와 message(OTP 코드가 포함된 텍스트)를 전달받아 이지어스의 발송 API로 전달합니다.

Step 3. EasyAuth API로 문자 발송 (완성된 코드)

이제 전체 동작하는 완성 코드를 작성해보겠습니다. 이지어스는 POST /send (발송)와 POST /verify (검증) 두 개의 심플한 엔드포인트를 제공합니다. 여기서는 Clerk이 검증을 대신해주므로 /send API만 사용하면 됩니다.

// app/api/webhooks/clerk-sms/route.ts
import { Webhook } from 'svix';
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');
  }

  // 1. 헤더에서 Svix 서명 추출
  const svix_id = req.headers.get("svix-id");
  const svix_timestamp = req.headers.get("svix-timestamp");
  const svix_signature = req.headers.get("svix-signature");

  if (!svix_id || !svix_timestamp || !svix_signature) {
    return new Response('Error occured -- no svix headers', {
      status: 400
    });
  }

  // 2. Body 파싱 및 서명 검증
  const payload = await req.json();
  const body = JSON.stringify(payload);
  const wh = new Webhook(WEBHOOK_SECRET);

  let evt: WebhookEvent;

  try {
    evt = wh.verify(body, {
      "svix-id": svix_id,
      "svix-timestamp": svix_timestamp,
      "svix-signature": svix_signature,
    }) as WebhookEvent;
  } catch (err) {
    console.error('Error verifying webhook:', err);
    return new Response('Error verifying webhook', { status: 400 });
  }

  // 3. sms.created 이벤트 처리 및 EasyAuth 연동
  if (evt.type === 'sms.created') {
    const { phone_number, message } = evt.data;

    try {
      // 이지어스(EasyAuth) API 호출
      const easyAuthRes = await fetch('https://api.easyauth.co.kr/send', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${process.env.EASYAUTH_API_KEY}`
        },
        body: JSON.stringify({
          to: phone_number,
          text: message
        })
      });

      if (!easyAuthRes.ok) {
        throw new Error('EasyAuth SMS Send Failed');
      }

      console.log(`SMS successfully sent to ${phone_number}`);
    } catch (error) {
      console.error('Failed to send SMS:', error);
      return new Response('Failed to send SMS', { status: 500 });
    }
  }

  return new Response('Webhook processed successfully', { status: 200 });
}

---

실무 팁 및 모범 사례 (Best Practices)

1. 보안 필수: 웹훅 엔드포인트는 외부에 노출되어 있습니다. 반드시 Svix를 활용한 서명 검증 로직을 포함하여 악의적인 사용자가 무단으로 SMS를 발송하는 것을 방지하세요.
2. 에러 핸들링: 통신사 장애나 번호 형식 오류로 인해 문자 발송이 실패할 수 있습니다. try-catch 블록으로 감싸고 실패 시 서버 로그(Datadog, Sentry 등)를 남기는 것이 좋습니다.
3. 100% 커스텀 구현 시: 만약 Clerk 없이 자체적인 인증 서버를 구축한다면, 이지어스의 POST /verify 엔드포인트를 활용해 검증 로직까지 단 몇 줄의 코드로 구현할 수 있습니다.

---

마무리

지금까지 Next.js와 Clerk, 그리고 이지어스(EasyAuth)를 활용하여 단 5분 만에 번거로운 서류 없이 SMS 인증을 연동하는 방법을 알아보았습니다.

개발자는 비즈니스 로직과 핵심 기능 개발에 집중해야 합니다. 사업자등록증 제출, 통신사 심사 대기로 시간을 낭비하지 마세요. 지금 바로 서류 없이 5분 만에 시작할 수 있는 EasyAuth에 가입하여 무료 체험 10건으로 여러분의 프로젝트에 SMS 인증을 도입해보세요!