알림·연동 V5 (beta)

봇의 웹훅 주소를 읽고 바꾸고 시험 발송합니다.

수집이 끝나면 웹훅 주소로 알립니다. 수동·주기 모든 수집에 적용되며, 여러 주기 기능이 닫힌 계정에서도 쓸 수 있습니다.

엔드포인트

  • GET /v5/api/bots/{bot_id}/notifications 웹훅 설정과 마지막 발송 결과
  • PUT /v5/api/bots/{bot_id}/notifications 웹훅 주소 설정·해제
  • POST /v5/api/bots/{bot_id}/notifications/test 테스트 발송

조회

칸설명
webhook_url·webhook_enabled웹훅 주소와 켜짐 여부.
webhook_token_set서명용 토큰이 있는지. 토큰 값은 내보내지 않습니다.
last_delivery마지막 발송 { kind, status, http_status, at }(kind는 real·test 등, 본문·서명은 주지 않음), 없으면 null.
요청 예시 
curl 'https://www.hashscraper.com/v5/api/bots/8f3a7c1e9b5d24f6/notifications' \
  -H 'Authorization: Bearer YOUR_API_KEY'
응답 예시 200 
{
  "result": "success",
  "version": "v5",
  "request_id": "req_5a8c1f1c-9b2d-4e7c-9abf-3f7e0a4d1b21",
  "elapsed_sec": 0.0123,
  "data": {
    "bot_id": "8f3a7c1e9b5d24f6",
    "webhook_url": "https://example.com/hooks/hashscraper",
    "webhook_enabled": true,
    "webhook_token_set": true,
    "last_delivery": {
      "kind": "real",
      "status": "success",
      "http_status": 200,
      "at": "2026-09-28T09:01:38+09:00"
    }
  }
}

주소 설정·해제

webhook_url에 http:// 또는 https:// 주소(공백 없이, 255자 이하)를 보내면 설정, null이면 해제입니다. 계정에 웹훅 토큰이 아직 없으면 화면과 같은 방식으로 만들어 둡니다. 내부망·사설 주소는 보낼 수 없습니다.

요청 예시 
curl -X PUT 'https://www.hashscraper.com/v5/api/bots/8f3a7c1e9b5d24f6/notifications' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "webhook_url": "https://example.com/hooks/hashscraper"
}'
요청 예시 
curl -X PUT 'https://www.hashscraper.com/v5/api/bots/8f3a7c1e9b5d24f6/notifications' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "webhook_url": null
}'

테스트 발송

화면의 "보내서 확인"과 같습니다. 주소가 없으면 422 WEBHOOK_NOT_SET입니다. 받는 쪽이 실패해도 테스트 자체는 끝난 것이라 200이고 결과는 data.success로 알립니다(응답을 못 받았으면 error에 이유). 재시도 중복 방지 키는 필수가 아닙니다.

요청 예시 
curl -X POST 'https://www.hashscraper.com/v5/api/bots/8f3a7c1e9b5d24f6/notifications/test' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H "Idempotency-Key: $(uuidgen)"
응답 예시 200 
{
  "result": "success",
  "version": "v5",
  "request_id": "req_5a8c1f1c-9b2d-4e7c-9abf-3f7e0a4d1b21",
  "elapsed_sec": 0.0123,
  "data": {
    "bot_id": "8f3a7c1e9b5d24f6",
    "success": true,
    "http_status": 200,
    "timed_out": false,
    "elapsed_ms": 184,
    "error": null
  }
}

웹훅 본문에 더해진 칸

웹훅 본문의 기존 칸은 이름·값·순서 그대로이고, 그 뒤에 세 칸이 더해졌습니다. 모든 웹훅(수동·주기)에 기본으로 들어갑니다.

  • trigger — manual·api·period·period_manual·excel.
  • plan — 주기가 시작한 수집이면 { id, name, label, scheduled_at }, 수동이면 null.
  • inputs — 그 수집에 쓴 조건 { param1: { name, value } }(v5 inputs 정의와 같은 모양).

X-HashScraper-Version 헤더는 1.0 그대로이고, 서명(X-Webhook-Signature)은 실제로 보낸 본문으로 계산하므로 받는 쪽 검증은 그대로 통과합니다. 주기를 늘린 봇은 주기마다 웹훅이 오니 plan으로 구분하세요.

웹훅의 plan.id는 숫자이고, v5 API 응답의 주기 id 는 글자("512")입니다. 비교할 때 맞춰 주세요.

Webhook body (new fields) 
{
  "schedule_id": 4821,
  "schedule_slug": "sample-shopping-bot",
  "schedule_name": "Sample shopping bot",
  "schedule_result_id": 239758028,
  "data_count": 1280,
  "completed_at": "2026-09-28T09:01:37.000+09:00",
  "job_start_time": "2026-09-28T09:00:03.000+09:00",
  "last_result_id": 90998721,
  "status": "completed",
  "trigger": "period",
  "plan": {
    "id": 512,
    "name": "주기 2",
    "label": "매주 월요일 09:00 (KST)",
    "scheduled_at": "2026-09-28T09:00:00+09:00"
  },
  "inputs": {
    "param1": {
      "name": "Keyword",
      "value": "sneakers"
    }
  },
  "empty_reason": null
}

함께 보면 좋은 가이드