Next.js 및 커스텀 사이트 (webhook)

사이트가 Next.js 앱이거나 헤드리스 프런트엔드이거나, 콘텐츠 API가 없는 그 밖의 형태라면 Clodix가 게시된 각 아티클을 JSON으로 내가 관리하는 URL에 POST할 수 있어요. 직접 만든 커스텀 사이트에 사용하는 연동이고, Zapier나 Make의 트리거로도 잘 작동해요.

연결하기

1. Settings → Publishing integrations를 열고 Next.js / Webhook을 클릭하세요.
2. 다음을 입력하세요.
   • Webhook URL — POST 요청을 받는 서버의 https:// 주소.
   • Signing secret (선택) — 설정하면 Clodix가 모든 요청에 서명하므로, 요청이 정말 Clodix에서 왔는지 검증할 수 있어요.
3. Connect를 클릭하세요. Clodix가 즉시 테스트 ping을 보내요. 연결에 성공하려면 엔드포인트가 2xx 상태로 응답해야 해요.

페이로드

모든 요청은 content-type: application/json 헤더와 함께 JSON으로 POST돼요. 봉투(envelope)에는 항상 event 필드가 있고, 본문 구조는 이벤트에 따라 달라요.

article.published — 아티클이 게시될 때 전송돼요.

{
  "event": "article.published",
  "article": {
    "title": "Best pour over coffee makers in 2026",
    "slug": "best-pour-over",
    "bodyHtml": "<p>...</p>",
    "metaDescription": "A guide to the best pour over coffee makers.",
    "imageUrl": "https://cdn.clodix.ai/covers/best-pour-over.jpg",
    "publishedAt": "2026-08-01T10:00:00.000Z"
  }
}

metaDescription, imageUrl, publishedAt은 아티클에 해당 값이 있을 때만 포함돼요.

article.unpublished — 아티클을 게시 취소할 때 전송돼요.

{ "event": "article.unpublished", "article": { "slug": "best-pour-over" } }

clodix.ping — Connect를 클릭할 때 한 번 전송되는 연결 테스트예요.

{ "event": "clodix.ping" }

헤더

헤더	값
content-type	application/json
x-clodix-event	본문의 event 필드와 같은 값이에요.
x-clodix-signature	서명 시크릿을 설정한 경우에만 전송돼요. 아래를 참고하세요.

서명 검증하기

서명 시크릿을 설정하면 Clodix는 시크릿을 키로 사용해 원본 요청 본문 그대로를 HMAC-SHA256으로 서명하고, x-clodix-signature: sha256=<hex digest>로 보내요.

// app/api/clodix/route.ts
import { createHmac, timingSafeEqual } from "crypto";
import { NextRequest, NextResponse } from "next/server";

const SECRET = process.env.CLODIX_WEBHOOK_SECRET!;

export async function POST(req: NextRequest) {
  const rawBody = await req.text(); // read as text BEFORE parsing JSON
  const signature = req.headers.get("x-clodix-signature") ?? "";

  const expected =
    "sha256=" + createHmac("sha256", SECRET).update(rawBody).digest("hex");

  const ok =
    signature.length === expected.length &&
    timingSafeEqual(Buffer.from(signature), Buffer.from(expected));

  if (!ok) {
    return NextResponse.json({ error: "invalid signature" }, { status: 401 });
  }

  const payload = JSON.parse(rawBody);
  // payload.event is "article.published" | "article.unpublished" | "clodix.ping"
  // ... upsert payload.article into your database/CMS by slug ...

  return NextResponse.json({ ok: true });
}

2xx로 응답하기

Clodix가 게시를 성공으로 처리하려면 엔드포인트가 성공 상태(200~299)로 응답해야 해요. 연결 테스트도 마찬가지예요. 2xx가 아닌 응답(또는 응답 없음)은 게시 실패로 처리돼요. 아티클은 Clodix에서 초안으로 남고, 연결 화면(또는 아티클의 Publish 버튼)에는 엔드포인트가 실제로 반환한 상태가 표시돼요.

엔드포인트는 표준 웹 포트에서 공개 주소여야 해요(:port 없이 https://… 또는 http://…). 로컬 또는 사설 네트워크의 주소나 그쪽으로 리디렉션되는 주소는, 아무것도 전송하기 전에 "This address isn't reachable from Clodix"라는 메시지와 함께 거부돼요.

게시된 URL 반환하기 (선택)

엔드포인트가 { "url": "https://yoursite.com/blog/best-pour-over" }로 응답하면, Clodix는 이를 아티클의 게시된 URL로 저장하고 검색 엔진에 새 페이지가 생겼다고 알리는 데 사용해요. 선택 사항이라서, 엔드포인트는 URL 없이 { "ok": true }만 반환해도 돼요.

FAQ

서명 시크릿이 꼭 필요한가요?

선택 사항이지만 외부에 공개되는 엔드포인트라면 권장해요. 요청이 URL을 짐작한 다른 사람이 아니라 정말 Clodix에서 왔는지 엔드포인트가 확인할 수 있는 유일한 방법이에요.

Clodix가 게시를 시도할 때 서버가 다운되어 있으면 어떻게 되나요?

게시가 실패하고 아티클은 초안으로 남아요. 이후 Clodix가 어떻게 하는지, 안전하게 다시 시도하는 방법은 게시 문제를 참고하세요.

내 서버 대신 Zapier나 Make와 함께 사용할 수 있나요?

네. Zapier나 Make가 "Catch Hook" / "Custom Webhook" 트리거용으로 제공하는 webhook URL을 Webhook URL 입력란에 붙여 넣고, 거기서부터 자동화를 만드세요.

관련 문서

• 웹사이트 연결하기
• 게시 문제
• 아티클 게시하기