Files
Gnuboard7/plugins/_bundled/sirsoft-message_bizppurio/docs/api/webhook.md
T
chym1217 77df8c9a7c feat(message_bizppurio): 발송 결과 기록 + webhook 수신 + 결과코드
문자·알림톡 발송 결과를 DB에 기록하고, 비즈뿌리오 webhook(URL PUSH)으로
도달 여부를 갱신한다. 결과코드를 사유+분류로 해석하고, 잔액 부족 시
관리자에게 쿨다운(기본 1시간) 내 1회만 알린다.

발송 결과를 확인하는 화면은 플러그인 독립 페이지 대신 코어 알림 이력에
얹는 방식(후속)으로 이관하기로 하여, 이번에 만든 독립 이력 화면과
화면 전용 백엔드는 제거했다. webhook 결과 저장·수신·해석 뼈대는 유지한다.
2026-07-28 12:36:21 +09:00

3.8 KiB

Webhook API 레퍼런스

소유: plugin sirsoft-message_bizppurio · 생성: php artisan api:docgen (실측 기반). @generated 블록은 재생성 시 갱신되며, 사람이 작성한 설명은 보존됩니다.


TL;DR (5초 요약)

1. 이 문서는 실제 API 호출로 실측한 Webhook 엔드포인트 레퍼런스입니다
2. 각 엔드포인트: 메서드/URI/권한 + 요청 파라미터 표 + 요청 예시(curl) + 실측 응답 필드 표 + 응답 예시(envelope)
3. 응답 필드의 예시값·응답 예시 JSON 은 실제 호출 응답에서 관측된 값입니다
4. 갱신: 코드 변경 후 php artisan api:docgen 재실행
5. 설명(TODO) 칸은 사람이 채웁니다

POST /api/plugins/sirsoft-message_bizppurio/webhook

  • 라우트명: api.plugins.sirsoft-message_bizppurio.webhook
  • 컨트롤러: Plugins\Sirsoft\MessageBizppurio\Controllers\BizppurioWebhookController@handle
  • 인증/권한: 공개 (인증 불필요)

요청 파라미터

이름 위치 타입 필수 허용값 용도
DEVICE body string 아니오 max 20
CMSGID body string 아니오 max 64
MSGID body string 아니오 max 64
PHONE body string 아니오 max 20
MEDIA body string 아니오 max 10
RESULT body string 예 max 10
REFKEY body string 예 max 32
TELRES body string 아니오 max 10
KAORES body string 아니오 max 10

요청 예시

POST /api/plugins/sirsoft-message_bizppurio/webhook HTTP/1.1
Host: api.example.com
Accept: application/json
Content-Type: application/json

{
    "DEVICE": "예시값",
    "CMSGID": "예시값",
    "MSGID": "예시값",
    "PHONE": "010-1234-5678",
    "MEDIA": "예시값",
    "RESULT": "예시값",
    "REFKEY": "예시값",
    "TELRES": "예시값",
    "KAORES": "예시값"
}

응답 필드 (data 내부)

응답 예시

에러 응답

상태코드 의미 발생 조건
422 Unprocessable Entity 요청 파라미터가 검증 규칙을 위반한 경우 (error.errors 에 필드별 메시지)

설명

비즈뿌리오가 문자·알림톡 발송 결과를 URL PUSH 로 통보하는 리포트 수신 엔드포인트다. 운영자가 이 주소를 비즈뿌리오에 등록하면(환경설정 화면의 리포트 수신 주소), 발송 후 결과가 이 엔드포인트로 전송된다.

  • 인증: 코어 토큰/IDV 미들웨어를 라우트 레벨에서 제외하고, 인증을 IP 화이트리스트로 대체한다. 화이트리스트 밖 IP 는 403.
  • 처리: REFKEY 로 발송 이력을 조회한다. 없으면(위조/미매칭) 200 으로 흡수한다. 이미 리포트가 반영된 이력(reported_at 존재)이면 replay 로 판정해 멱등 처리한다. 그 외에는 RESULT 코드를 분류(성공/실패/잔액부족)해 상태를 전이하고 media·fallback_status·raw_payload·reported_at 을 기록한다.
  • 잔액부족: RESULT 가 9070(문자)/7436(알림톡)이면 이력을 실패로 뒤집고 관리자에게 자체 알림을 1회 발송한다.
  • 응답은 항상 200 이다(비즈뿌리오가 실패 응답을 재전송하지 않도록). replay 멱등이 중복 처리를 막는다.