๋ณธ๋ฌธ์œผ๋กœ ๊ฑด๋„ˆ๋›ฐ๊ธฐ
Pellio

์›นํ›…

2026๋…„ 10์›” 2์ผ ์—…๋ฐ์ดํŠธ
์ด ํŽ˜์ด์ง€์˜ ๋‚ด์šฉ

Settings โ†’ Developers โ†’ Webhooks(์„ค์ • โ†’ ๊ฐœ๋ฐœ์ž โ†’ ์›นํ›…)์—์„œ ์—”๋“œํฌ์ธํŠธ๋ฅผ ์ถ”๊ฐ€ํ•ฉ๋‹ˆ๋‹ค(์†Œ์œ ์ž์™€ ๊ด€๋ฆฌ์ž๋งŒ ๊ฐ€๋Šฅ). ์—”๋“œํฌ์ธํŠธ๋Š” ๊ณต๊ฐœ๋œ HTTPS ์ฃผ์†Œ์—ฌ์•ผ ํ•ฉ๋‹ˆ๋‹ค. ๋ฐ›์„ ์ด๋ฒคํŠธ๋ฅผ ์„ ํƒํ•˜์„ธ์š”. All events๋ฅผ ์ผœ ๋‘๊ฑฐ๋‚˜(๋‚˜์ค‘์— Pellio์— ์ถ”๊ฐ€๋˜๋Š” ์ด๋ฒคํŠธ๋„ ํฌํ•จ), ๋„๊ณ  ์›ํ•˜๋Š” ์ด๋ฒคํŠธ๋ฅผ ๊ณ ๋ฅผ ์ˆ˜ ์žˆ์Šต๋‹ˆ๋‹ค. Pellio๋Š” ์—”๋“œํฌ์ธํŠธ์˜ ์„œ๋ช… ์‹œํฌ๋ฆฟ์„ ํ•œ ๋ฒˆ๋งŒ ๋ณด์—ฌ ์ค๋‹ˆ๋‹ค.

๊ฐ ์—”๋“œํฌ์ธํŠธ์—๋Š” ์ˆ˜์‹ ํ•˜๋Š” ์ด๋ฒคํŠธ ๋ชฉ๋ก๊ณผ ํ•จ๊ป˜ ๋‹ค์Œ ์ž‘์—…์ด ํ‘œ์‹œ๋ฉ๋‹ˆ๋‹ค.

  • Edit events: ์ˆ˜์‹ ํ•  ์ด๋ฒคํŠธ๋ฅผ ๋ณ€๊ฒฝํ•ฉ๋‹ˆ๋‹ค. Save events๋ฅผ ๋ˆ„๋ฅด๋ฉด ์ฆ‰์‹œ ์ ์šฉ๋ฉ๋‹ˆ๋‹ค.
  • Send test: ์ˆ˜์‹  ์ด๋ฒคํŠธ ์„ค์ •๊ณผ ๊ด€๊ณ„์—†์ด ํ•ด๋‹น ์—”๋“œํฌ์ธํŠธ๋กœ webhook.test ์ด๋ฒคํŠธ๋ฅผ ๋ณด๋ƒ…๋‹ˆ๋‹ค.
  • Deliveries: ์ตœ๊ทผ 50๋ฒˆ์˜ ์ „์†ก ์‹œ๋„(๋Œ€๊ธฐ ์ค‘, ์ „์†ก๋จ, ์‹คํŒจ)์™€ ์‘๋‹ต์„ ๋ณด์—ฌ ์ค๋‹ˆ๋‹ค.
  • Rotate secret: ์„œ๋ช… ์‹œํฌ๋ฆฟ์„ ๊ต์ฒดํ•ฉ๋‹ˆ๋‹ค. ์ƒˆ ์‹œํฌ๋ฆฟ์€ ํ•œ ๋ฒˆ๋งŒ ํ‘œ์‹œ๋˜๊ณ  ๊ธฐ์กด ์‹œํฌ๋ฆฟ์€ ์ฆ‰์‹œ ๋ฌดํšจํ™”๋˜๋ฏ€๋กœ, ์—”๋“œํฌ์ธํŠธ๋ฅผ ๋ฐ”๋กœ ์—…๋ฐ์ดํŠธํ•˜์„ธ์š”.
  • Remove: ์—”๋“œํฌ์ธํŠธ๋กœ ์ „์†ก์„ ์ค‘๋‹จํ•ฉ๋‹ˆ๋‹ค.

API์—์„œ๋Š” POST /v1/webhooks๊ฐ€ url๊ณผ events(๋นˆ ๋ชฉ๋ก์€ ๋ชจ๋“  ์ด๋ฒคํŠธ)๋ฅผ ๋ฐ›๊ณ , PATCH /v1/webhooks/{id}๋กœ events๋ฅผ ๋ณ€๊ฒฝํ•˜๋ฉฐ, POST /v1/webhooks/{id}/rotate-secret์€ ์ƒˆ secret์„ ๋ฐ˜ํ™˜ํ•ฉ๋‹ˆ๋‹ค.

์ด๋ฒคํŠธ

๋ชจ๋“  ์š”์ฒญ ๋ณธ๋ฌธ์€ { "id", "event", "createdAt", "data" } ํ˜•์‹์ž…๋‹ˆ๋‹ค.

event ๋ฐœ์ƒ ์‹œ์  data
video.created ์—…๋กœ๋“œ, ๋…นํ™”, URL ๊ฐ€์ ธ์˜ค๊ธฐ๋กœ ๋™์˜์ƒ์ด ์ƒ์„ฑ๋˜์—ˆ์„ ๋•Œ id, title
video.ready ๋™์˜์ƒ ์ฒ˜๋ฆฌ๊ฐ€ ๋๋‚ฌ์„ ๋•Œ(๊ต์ฒด๋‚˜ ์ž๋ฅด๊ธฐ ํ›„ ํฌํ•จ) id, title, status, version, durationSeconds, width, height, errorMessage
video.failed ์ƒˆ ๋™์˜์ƒ์„ ์ฒ˜๋ฆฌํ•˜์ง€ ๋ชปํ–ˆ์„ ๋•Œ video.ready์™€ ๋™์ผ
video.deleted ๋™์˜์ƒ์ด ํœด์ง€ํ†ต์œผ๋กœ ์ด๋™(trashed: true)๋˜๊ฑฐ๋‚˜ ์˜๊ตฌ ์‚ญ์ œ๋˜์—ˆ์„ ๋•Œ id, title, trashed
video.watched ์‹๋ณ„๋œ ์‹œ์ฒญ์ž(์ด๋ฉ”์ผ ์–‘์‹, ?email= ๋งํฌ, WordPress ์‚ฌ์ดํŠธ๋ฅผ ํ†ตํ•ด ์‹๋ณ„)๊ฐ€ ๋™์˜์ƒ์„ ์‹œ์ž‘ํ•˜๊ฑฐ๋‚˜, 25%, 50%, 75%๋ฅผ ์ง€๋‚˜๊ฑฐ๋‚˜, ๋๊นŒ์ง€ ์‹œ์ฒญํ–ˆ์„ ๋•Œ(์—ฌ๋Ÿฌ ๋ฒˆ ๋ฐฉ๋ฌธํ•œ ์‹œ์ฒญ์„ ํ•ฉ์ณ 90%). ์‹œ์ฒญ์ž, ๋™์˜์ƒ, ๋งˆ์ผ์Šคํ†ค๋ณ„๋กœ ํ•œ ๋ฒˆ์”ฉ ๋ฐœ์ƒํ•ฉ๋‹ˆ๋‹ค. video(id, title), viewer(email, name), progress(0, 25, 50, 75, 100), milestone(started, 25%, 50%, 75%, completed), completed
lead.captured ๋ˆ„๊ตฐ๊ฐ€ ์ด๋ฉ”์ผ ์–‘์‹์„ ์ œ์ถœํ–ˆ์„ ๋•Œ id, email, name, fields, video(id, title), createdAt

์ „์†ก

Pellio๋Š” User-Agent: Pellio-Webhooks/1 ํ—ค๋”์™€ ํ•จ๊ป˜ POST ์š”์ฒญ์„ ๋ณด๋‚ด๊ณ  ์ตœ๋Œ€ 10์ดˆ ๋™์•ˆ ๊ธฐ๋‹ค๋ฆฝ๋‹ˆ๋‹ค. 2xx ์‘๋‹ต์€ ๋ชจ๋‘ ์ „์†ก ์„ฑ๊ณต์œผ๋กœ ์ฒ˜๋ฆฌํ•ฉ๋‹ˆ๋‹ค. ๋ฆฌ๋””๋ ‰์…˜์€ ๋”ฐ๋ผ๊ฐ€์ง€ ์•Š์œผ๋ฏ€๋กœ 3xx๋Š” ์‹คํŒจ๋กœ ์ฒ˜๋ฆฌ๋ฉ๋‹ˆ๋‹ค. ์‹คํŒจํ•œ ์ „์†ก์€ ์ด 6๋ฒˆ๊นŒ์ง€ ์‹œ๋„ํ•˜๋ฉฐ, ์ฒซ ์žฌ์‹œ๋„ ์ „์— 20์ดˆ๋ฅผ ๊ธฐ๋‹ค๋ฆฌ๊ณ  ์ดํ›„ ๋Œ€๊ธฐ ์‹œ๊ฐ„์„ ๋‘ ๋ฐฐ์”ฉ ๋Š˜๋ ค ์ตœ๋Œ€ 320์ดˆ๊นŒ์ง€ ๊ธฐ๋‹ค๋ฆฝ๋‹ˆ๋‹ค.

์„œ๋ช… ํ™•์ธํ•˜๊ธฐ

๋ชจ๋“  ์š”์ฒญ์—๋Š” ์—”๋“œํฌ์ธํŠธ์˜ ์‹œํฌ๋ฆฟ์œผ๋กœ ๋งŒ๋“  Pellio-Signature ํ—ค๋”๊ฐ€ ํฌํ•จ๋ฉ๋‹ˆ๋‹ค: t=<unix time>,v1=<hex HMAC-SHA256 of "t.body">. ๊ฐ€๊ณตํ•˜์ง€ ์•Š์€ ์›๋ณธ ์š”์ฒญ ๋ณธ๋ฌธ์œผ๋กœ ์„œ๋ช…์„ ํ™•์ธํ•˜์„ธ์š”.

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(header, rawBody, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // 5-minute tolerance
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

์ด ๊ธ€์ด ๋„์›€์ด ๋˜์—ˆ๋‚˜์š”?

์•„์ง ํ•ด๊ฒฐ๋˜์ง€ ์•Š์•˜๋‚˜์š”?๋ฉ”์‹œ์ง€๋ฅผ ๋ณด๋‚ด ์ฃผ์‹œ๋ฉด ๋‹ด๋‹น์ž๊ฐ€ ๋‹ต๋ณ€๋“œ๋ฆด๊ฒŒ์š”.