게시물이 게시되는 순간, 또는 실패하는 순간을 바로 확인
URL을 한 번 등록하면 전송이 완료될 때마다 FoPost가 호출해요. 각 이벤트에는 게시물 id, 계정, 플랫폼, 퍼머링크 또는 오류 메시지가 담겨 있어 시스템이 폴링 없이 대응할 수 있어요.
curl -X POST https://api.fopost.com/v1/webhooks \
-H "X-API-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"workspaceId": "9b2f6c1e-...",
"url": "https://yourbrand.com/hooks/social",
"events": ["delivery.published", "delivery.failed", "post.published", "post.failed"]
}'완료 시 발생
계정별 전송마다 이벤트 하나가 네트워크가 승인하거나 거부하는 즉시 전송돼요.
서명
모든 요청에 서명 헤더가 포함되어 저희가 보낸 것인지 확인할 수 있어요.
재시도
2xx가 아닌 응답은 이벤트를 폐기하기 전에 백오프로 재시도해요.
게시의 전체 수명 주기를 다루는 이벤트
delivery.published는 네트워크가 한 계정의 전송을 승인하면 퍼머링크와 함께 발생해요. delivery.failed는 게시되지 않을 때 플랫폼의 오류 메시지와 함께 발생해요. post.published와 post.failed는 모든 계정의 전송이 완료된 뒤 게시물당 한 번 발생해요.
웹훅 레퍼런스 읽기{
"event": "delivery.published",
"data": {
"postId": "7d3e0a52-...",
"postAccountId": "a3c5e7f9-...",
"accountId": "4a71d80b-...",
"platform": "linkedin",
"externalUrl": "https://linkedin.com/feed/update/..."
},
"timestamp": "2026-09-01T09:00:07Z"
}delivery.published
저장하거나 CMS에서 다시 연결할 수 있는 퍼머링크.
delivery.failed
네트워크의 자체 오류 메시지를 받으므로 추측하지 않고 원인을 해결할 수 있어요.
워크스페이스별
웹훅은 하나의 워크스페이스에 속하며 그 워크스페이스의 게시물만 봐요.
처리하기 전에 페이로드를 검증
각 요청은 웹훅을 만들 때 반환되는 시크릿으로 서명돼요. 원본 본문으로 서명을 계산해 헤더와 비교하고, 일치하지 않으면 거부하세요. 2xx로 빠르게 응답하고 실제 작업은 그 뒤에 처리하세요.
서명 검증 보기app.post('/hooks/social', async (req, res) => {
const signature = req.header(SIGNATURE_HEADER) // header name is in the docs;
if (!verify(req.rawBody, signature, process.env.WEBHOOK_SECRET)) {
return res.status(401).end();
}
const { event, data } = req.body;
await queue.add(event, data);
res.status(200).end();
});서명 헤더
생성할 때 받은 시크릿으로 검증하세요. 교체하려면 다시 생성하면 돼요.
타임스탬프 포함
timestamp로 오래된 재전송을 무시하고 이벤트 순서를 올바르게 정할 수 있어요.
id 기반 멱등성
재시도에는 같은 이벤트 id가 담겨 있어 중복 전송을 쉽게 걸러낼 수 있어요.
코드로 엔드포인트 생성, 조회, 삭제
웹훅은 일반적인 API 객체예요. 환경마다 하나씩 만들고, 목록을 조회해 등록 내역을 점검하고, 더 이상 필요 없는 것은 삭제하세요. 개발 중에는 스테이징 URL을 지정하고 호출 한 번으로 프로덕션으로 바꾸세요.
개발 시작하기
엔드포인트 목록
GET /v1/webhooks가 모든 URL과 각 URL이 구독하는 이벤트를 보여 줘요.
환경별 설정
스테이징용 URL을 따로 등록해 테스트 게시물이 프로덕션에 닿지 않게 하세요.
webhooks 범위
엔드포인트 관리에는 별도의 범위가 필요해요. 게시 전용 키로는 추가할 수 없어요.