내 뉴스레터 폼의 가입을 Kit로 보내기

내 폼을 Ikiform으로 POST하고, Kit v4 API를 최대 세 번 호출하는 릴레이로 Ikiform 웹훅을 보내세요. 구독자 생성, Kit 폼에 추가, 가입 위치 태그입니다. inactive로 만들고 인센티브 이메일이 켜진 폼에 추가하면 Kit가 자체 확인 이메일을 보낼 것입니다. Kit는 이를 대량 엔드포인트에 대해서만 문서화하고 있으므로 내 주소로 한 번 테스트하세요. Kit API 키는 릴레이가 가지고 있고, 페이지는 절대 보지 못합니다.

Kit에서 다른 점

Kit는 가입을 별도 객체로 나눕니다. subscriber는 사람입니다. form은 그 사람이 온 곳이며 확인 이메일을 담고 있습니다. Kit는 이를 인센티브 이메일이라고도 부르며, 이것이 더블 옵트인 단계입니다. tag는 세그먼트용 라벨입니다. v4 API에는 각각의 엔드포인트가 있고, form과 tag 엔드포인트 모두 subscriber가 먼저 존재해야 합니다. 그래서 Ikiform 가입 하나가 순서대로 이어지는 짧은 호출이 됩니다.

Kit 설정하기

1. Kit에서 "Website signup" 같은 이 가입용 폼을 만드세요. 임베드하지는 않으며, 구독자의 출처 기록이자 인센티브 이메일이 있는 곳입니다.
2. 더블 옵트인을 원한다면 폼 설정을 열어 인센티브 이메일을 켜세요. 이메일을 작성하고 확인 링크가 갈 곳을 설정하세요.
3. Kit 앱이나 API의 폼 목록 엔드포인트에서 폼의 숫자 ID를 찾으세요. 원한다면 위치마다 태그를 만들고 ID를 기록하세요.
4. Kit 개발자 설정에서 v4 API 키를 만들고 릴레이의 환경 변수용으로 보관하세요.

릴레이

Next.js 라우트 핸들러가 웹훅을 받고, 작은 모듈이 Kit와 통신합니다. 같은 두 파일이 공개 HTTPS URL을 주는 어떤 Node나 edge 호스트에서든 동작합니다.

const KIT = "https://api.kit.com/v4";

const TAGS: Record<string, number> = {
  footer: 1111111,
  post: 2222222,
};

function call(path: string, body: Record<string, unknown>) {
  return fetch(`${KIT}${path}`, {
    method: "POST",
    headers: {
      "X-Kit-Api-Key": process.env.KIT_API_KEY!,
      "Content-Type": "application/json",
      Accept: "application/json",
    },
    body: JSON.stringify(body),
  });
}

export async function addToKit(signup: { email: string; firstName?: string; source: string; referrer?: string }) {
  const created = await call("/subscribers", {
    email_address: signup.email,
    first_name: signup.firstName ?? null,
    state: "inactive",
  });
  if (!created.ok) return created;

  const joined = await call(`/forms/${process.env.KIT_FORM_ID}/subscribers`, {
    email_address: signup.email,
    referrer: signup.referrer ?? null,
  });
  if (!joined.ok) return joined;

  const tag = TAGS[signup.source];
  if (!tag) return joined;
  return call(`/tags/${tag}/subscribers`, { email_address: signup.email });
}

import { verifyWebhook, WebhookVerificationError } from "@ikiform/sdk/webhooks";
import { addToKit } from "@/lib/kit";

export async function POST(request: Request) {
  const payload = await request.text();
  let event;
  try {
    event = await verifyWebhook({ payload, headers: request.headers, secret: process.env.IKIFORM_WEBHOOK_SECRET! });
  } catch (error) {
    if (error instanceof WebhookVerificationError) return new Response(error.reason, { status: 400 });
    throw error;
  }
  if (event.type !== "submission.created") return new Response(null, { status: 204 });

  const { email, first_name, consent, source } = event.data.fields;
  if (consent !== true || typeof email !== "string") return new Response("Skipped", { status: 200 });

  const answer = await addToKit({
    email,
    firstName: typeof first_name === "string" ? first_name : undefined,
    source: typeof source === "string" ? source : "unknown",
    referrer: typeof event.data.meta.referrer === "string" ? event.data.meta.referrer : undefined,
  });

  if (answer.status === 429) return new Response("Kit rate limit", { status: 503, headers: { "retry-after": "60" } });
  if (!answer.ok) return new Response(`Kit answered ${answer.status}: ${await answer.text()}`, { status: 502 });
  return new Response(null, { status: 204 });
}

IKIFORM_WEBHOOK_SECRET=whsec_...
KIT_API_KEY=your-v4-api-key
KIT_FORM_ID=1234567

• X-Kit-Api-Key는 Kit v4 API가 개인 API 키를 받는 방식입니다. OAuth는 다른 사람이 설치하는 앱용이므로, 내 목록을 위한 릴레이에는 필요 없습니다.
• state: "inactive"를 보내야 새 구독자가 클릭할 때까지 미확인 상태로 남습니다. 빼면 Kit가 active로 만들고, 같은 엔드포인트로는 나중에 상태를 바꿀 수 없습니다.
• 페이지의 referrer가 폼의 referrer로 Kit에 전달되므로, Kit에서 독자가 어느 글에서 왔는지 볼 수 있습니다.
• Kit의 오류 본문이 502에 담기므로 Ikiform의 전달 로그에 Kit 자체 메시지가 표시됩니다.
• TAGS에서 각 source 값을 태그 ID에 매핑하세요. 태그가 없는 source는 세 번째 호출을 건너뜁니다.

Ikiform 대시보드의 Webhooks에서 라우트의 URL을 추가하고, 뉴스레터 폼을 고르고, whsec_ 시크릿을 IKIFORM_WEBHOOK_SECRET에 복사하세요. URL 규칙과 각 응답의 의미는 모두 웹훅 문서에 있습니다.

레이트 리밋과 재시도

Kit는 API 키당 롤링 60초에 120개의 요청을 허용합니다. 가입마다 두세 번 호출하므로 Kit가 429로 응답하기 전까지 분당 약 40~60건이 들어갑니다. 푸터 폼에는 충분하고, 글이 화제가 된 날에는 빠듯합니다.

Kit가 429를 보내면 릴레이는 Retry-After와 함께 503으로 응답하고, Ikiform은 기다렸다가 다시 시도합니다. 재시도는 전체 순서를 처음부터 실행합니다. 안전합니다. 생성은 기존 구독자에 대해 200을 반환하고, 이미 폼에 있는 사람을 추가하면 200을 반환합니다. Kit의 대량 폼 문서에 따르면 이미 폼에 있는 사람은 인센티브 이메일을 다시 받지 않습니다. 단일 엔드포인트에 대해서는 언급이 없으므로 내 주소로 재시도를 테스트하세요. 이미 끝낸 재시도를 건너뛰고 싶다면 자체 서버에서 각 webhook-id를 기록하는 방법을 보여 줍니다.

주의할 점

• 커스텀 필드는 먼저 존재해야 합니다. 생성 호출에 fields를 추가한다면 last_name 같은 각 필드의 키를 쓰고, 보내기 전에 Kit에서 필드를 만드세요.
• 활성 구독자는 활성으로 유지됩니다. 생성은 기존 구독자의 상태를 바꾸지 않으므로, 확인된 독자가 다시 가입해도 다시 확인을 요청받지 않습니다.
• 수신 거부한 독자. 수신 거부한 뒤 다시 가입한 독자는 이미 존재하므로 생성은 200을 반환하고 상태를 바꾸지 않습니다. 이들을 어떻게 다룰지 Kit에서 확인하세요.
• 폼 하나, 위치 여럿. 웹사이트에는 Kit 폼 하나를 쓰고 위치는 태그로 구분하세요. Kit 폼이 여러 개면 맞춰 관리해야 할 인센티브 이메일도 여러 개가 됩니다.
• Ikiform의 이메일은 없습니다. Ikiform은 폼을 작성한 사람에게 이메일을 보내지 않습니다. 알림 이메일은 나와 팀에게만 가므로 자동 응답, 확인 이메일, 더블 옵트인이 없습니다. 그런 이메일은 웹훅으로 트리거해 이메일 도구에서 보내세요.

작동 확인하기

1. Ikiform의 엔드포인트에서 Send test를 누르세요. 전달에 204가 표시되고 Kit에는 변화가 없습니다.
2. 내 주소로 페이지에서 구독하세요. 전달에 204가 표시됩니다.
3. Kit에서 구독자가 위치 태그와 함께 미확인 상태로 폼에 표시됩니다.
4. 인센티브 이메일이 도착합니다. 링크를 클릭하면 구독자가 확인됨이 됩니다.
5. 같은 주소로 다시 구독하세요. 전달에 204가 표시되고 두 번째 인센티브 이메일은 오지 않습니다.
6. 잠깐 KIT_FORM_ID를 틀린 값으로 설정하세요. 전달에 Kit의 404 메시지와 함께 502가 표시됩니다.

질문