Webhook

설정 예상 시간: 7분

Webhook은 대부분의 직접 제작 또는 AI 제작 사이트에 권장됩니다. 웹사이트 구현 시간은 예상 설정 시간에 포함되지 않습니다.

준비

웹사이트를 만드는 AI 개발 도구 또는 유지보수 담당자.
웹사이트 호스팅 설정 변경 권한.

웹사이트 도구에 연결 안내 전달

아래 전체 안내를 개발 도구에 복사해 기존 페이지와 디자인을 유지하면서 Surpasso를 블로그에 연결하도록 요청합니다. 블로그가 없다면 추가하도록 합니다.

연결 안내 보기

Surpasso는 기업이 SEO 및 GEO 글을 기획하고 작성해 게시하도록 돕는 제품입니다. 기존 웹사이트를 Surpasso에 연결하세요. 먼저 프레임워크, 블로그 경로, 글 저장 방식, 디자인, 배포 방식을 확인하고 기존 기능을 우선 재사용합니다. 사이트를 다시 만들거나 기존 글을 삭제 또는 덮어쓰지 마세요.

Webhook을 사용합니다. Surpasso가 글을 보내고 웹사이트가 저장해 표시합니다. 기존 CMS 쓰기 로직을 재사용해 공개 HTTPS POST 수신 주소(예: /api/surpasso-webhook)를 추가하세요. 블로그가 없다면 현재 디자인을 유지하면서 필요한 글 저장소, 목록, 상세 페이지를 추가합니다. 먼저 배포 가능한 수신 URL을 반환하세요. SURPASSO_WEBHOOK_SECRET이 설정되기 전에는 요청을 반드시 거부하고 검증을 끄지 마세요. 이후 Surpasso에 URL을 저장하고 서명 비밀 키를 받은 뒤 웹사이트 배포 환경에 SURPASSO_WEBHOOK_SECRET을 설정하고 테스트합니다.

JSON 봉투: {schemaVersion:"1",event,deliveryId,idempotencyKey,occurredAt,article}. 헤더: x-surpasso-timestamp, x-surpasso-signature(sha256=16진수 서명), x-surpasso-event, x-surpasso-delivery. 수정하지 않은 rawBody로 HMAC-SHA256(secret, timestamp + "." + rawBody)를 계산하고 상수 시간 비교와 5분 시간 범위로 검증하며 잘못된 구조를 거부합니다. integration.test는 article:null입니다. 검증 후 콘텐츠를 만들지 않고 2xx를 반환합니다. article.draft_created는 비공개 초안 저장, article.published는 공개, article.updated는 기존 게시 상태를 유지한 채 같은 글을 업데이트합니다. 현재 게시 취소/삭제 이벤트는 없으므로 자동 삭제를 지원한다고 말하지 마세요.

필드 매핑: id = 안정적인 글 식별자, revision = 콘텐츠 버전, title = 제목, slug = 글 경로, excerpt = 요약, contentMarkdown / contentHtml = 본문(기존 편집기에 맞는 형식을 사용하고 HTML을 안전하게 처리), metaTitle / metaDescription = SEO 메타데이터, featuredImage.url / alt = 대표 이미지와 대체 텍스트, images = 본문 이미지, author / authorType / authorUrl = 작성자, editor / reviewer 및 각 Type / Url = 편집 정보, categories / tags = 분류, language = 콘텐츠 언어, contentFamilyId / alternates = 다국어 관계와 링크, structuredData = 구조화 데이터, canonicalUrl = 표준 URL. 최종 URL에는 웹사이트의 실제 공개 경로를 사용하고 잘못된 canonical을 복사하지 마세요. null을 안전하게 처리하고 지원하지 않는 선택 필드가 게시를 막지 않게 하세요.

article.id와 로컬 글의 연결을 Product/brandId별로 영구 저장하고 오래된 revision을 거부합니다. deliveryId / idempotencyKey는 전송 중복 제거를 위해 영구 저장하며 전송 키를 글 식별자로 사용하지 마세요. 처리된 중복에는 성공을 반환하되 글을 다시 만들지 않습니다. 쓰기 성공 또는 영구 큐 수락 후에만 2xx를 반환합니다. 발신자는 12초 후 시간 초과되고 리디렉션을 거부합니다. 잘못된 서명, 오래된 타임스탬프, 연결 테스트, 초안, 게시, 업데이트, 중복 전송, 오래된 리비전을 테스트하세요.

필요한 검사를 실행한 뒤 일반 사용자가 이해할 수 있게 변경 기능, 배포 단계, 설정할 환경 변수 이름과 배포 대시보드, Surpasso에 다시 입력할 URL, 글 게시와 업데이트 확인 방법을 설명하세요. 비밀 값은 웹사이트 배포 플랫폼의 환경 변수에서 설정하도록 안내하고 채팅, Git, 브라우저 코드에는 절대 넣지 마세요.

도구가 변경 사항을 배포하고 https://example.com/api/surpasso-webhook 같은 실제 수신 주소를 주어야 합니다. 홈페이지나 예시 주소를 그대로 사용하지 마세요.

주소와 연결 키 저장

Integrations → Custom → Webhook에서 수신 URL이 있음을 선택해 주소를 저장합니다.
한 번만 전체 표시되는 연결 키를 복사합니다.
호스팅 환경 변수 SURPASSO_WEBHOOK_SECRET로 저장하고 사이트를 재배포합니다.
Surpasso로 돌아와 완료를 확인합니다.

테스트와 글 확인

연결 테스트는 테스트 메시지만 보내고 글을 만들지 않습니다. 성공 후 Content Calendar에서 초안을 보내 본문과 이미지를 확인하고 발행하세요. 같은 글을 수정·재전송해 중복이 아니라 기존 글이 업데이트되는지 확인합니다.

삭제와 비공개 전환은 웹사이트 블로그 관리자에서 합니다. Webhook은 외부 글을 자동 삭제하지 않습니다. Make, Zapier, n8n도 가능하지만 실제 수신 URL, 서명 확인, 블로그 저장, 글과 수정의 실제 검증이 필요합니다.

테스트 실패, 글 누락 또는 중복

구현 배포, 로그인이나 리디렉션 없는 HTTPS 주소, 키 저장 후 재배포를 확인합니다. 수신기는 12초 안에 응답하고 같은 delivery를 중복 생성하지 않으며 오래된 revision이 새 내용을 덮어쓰지 않게 해야 합니다. 결과를 확인할 수 없다는 안내가 있으면 재시도 전에 사이트를 확인하세요.

키 분실 또는 노출

기존 키 사용을 중단하고 Surpasso에서 Webhook을 해제·재연결해 새 키를 호스팅에 저장한 뒤 재배포·재테스트합니다. 전체 기존 키는 다시 표시되지 않습니다.

기술 참고: 이벤트와 서명

각 JSON POST에는 schemaVersion: "1", event, deliveryId, idempotencyKey, occurredAt, article이 있습니다. integration.test는 확인만, article.published는 발행, article.updated는 같은 글을 상태 유지로 업데이트합니다.

timestamp + "." + rawBody를 HMAC-SHA256으로 계산해 x-surpasso-signature의 sha256= 값과 일정 시간 비교하고 5분을 벗어난 시각은 거부합니다. 구조, 중복, revision도 검증해야 하며 서명 확인만으로는 완전한 수신기가 아닙니다.