웹훅

POST https://api.beatapi.io/v1/webhooks

BeatAPI 작업 완료 알림(선택 사항)을 받을 웹훅 엔드포인트를 만듭니다.

인증

Authorization   string   필수

BeatAPI API 키를 Bearer 토큰으로 보내세요. 키는 대시보드에서 만들 수 있습니다.

Authorization: Bearer <BEATAPI_API_KEY>

영구 API 키는 신뢰할 수 있는 서버에만 보관하세요. 요청 본문에는 Content-Type: application/json이 필요합니다. Idempotency-Key는 엔드포인트가 지원하는 경우 선택 사항이며, 완전히 같은 본문으로 안전하게 재시도하려면 사용하는 것이 좋습니다.

요청 본문

url   string   필수

BeatAPI 작업 이벤트를 받는 공개 HTTPS 콜백 URL입니다. localhost나 사설 네트워크 URL은 사용하지 마세요.

형식: uri

description   string   선택

계정에서 엔드포인트를 구분하기 위한 내부 라벨입니다(선택 사항).

events   string[]   선택

전달할 작업 이벤트입니다. 생략하면 task.succeeded와 task.failed를 모두 구독합니다.

응답

요청에 성공하면 HTTP 201을 반환합니다.

{
  "data": {
    "id": "wh_9aBcD",
    "object": "webhook_endpoint",
    "url": "https://example.com/beatapi-webhook",
    "description": "Production webhook",
    "events": [
      "task.succeeded",
      "task.failed"
    ],
    "status": "active",
    "secret": "whsec_example_store_this_once",
    "created_at": 1782210000,
    "updated_at": 1782210000
  }
}

콜백 서명 검증

BeatAPI는 모든 전달에 x-beatapi-event, x-beatapi-timestamp, x-beatapi-signature를 보냅니다. 다음 값으로 기대 서명(hex 인코딩한 HMAC-SHA256)을 계산하세요.

timestamp + "." + raw_request_body

이 생성 요청이 반환한 엔드포인트 secret을 사용하세요. 서명은 상수 시간으로 비교하고, JSON 파싱 전에 정확한 원시 바이트를 검증하며, 재전송 공격을 막기 위해 5분보다 오래된 타임스탬프는 거부하세요.

엔드포인트 관리

• GET /v1/webhooks는 웹훅 엔드포인트 목록을 조회합니다.
• GET /v1/webhooks/{id}는 웹훅 엔드포인트를 조회합니다.
• PATCH /v1/webhooks/{id}는 웹훅 엔드포인트를 수정합니다.
• DELETE /v1/webhooks/{id}는 웹훅 엔드포인트를 삭제합니다.

다음 단계

페이로드를 파싱하기 전에 모든 콜백 서명을 검증하세요. 전달이 지연되거나 실패해도 GET /v1/tasks/{task_id} 폴링이 기준 정보입니다.

오류