관리번호 Webhook
관리번호 발급 링크로 엔드유저가 본인인증을 마치고 번호가 개통됐을 때 전송되는 assignment.completed Webhook 을 안내합니다.
관리번호 Webhook 은 관리번호 발급 링크를 통해 엔드유저가 본인인증을 완료하고 번호가 실제로 개통된 직후 전송됩니다. 계정 레벨에서 REST API 로 등록합니다.
이 이벤트가 없으면 발급 결과를 알기 위해 GET /v1/accounts/{accountId}/assignment-links/{linkId} 를
주기적으로 조회(폴링)해야 합니다. Webhook 을 등록하면 폴링 없이 개통 시점에 바로 받을 수 있습니다.
등록
POST /v1/accounts/{accountId}/webhooks
Body:
{
"url": "https://my-app.com/assignment-webhook",
"events": ["assignment.completed"]
}이벤트 종류
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
| assignment.completed | event | 선택 | 엔드유저가 본인인증·약관동의를 마치고 070번호가 본인 명의로 개통 완료됨 |
링크가 만료(expired)되거나 취소(revoked)된 경우에는 이벤트가 발생하지 않습니다.
개통에 성공한 경우에만 전송됩니다.
요청 파라미터
모든 요청은 Content-Type: application/x-www-form-urlencoded POST 입니다.
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
| Event | string | 필수 | 고정값 assignment.completed |
| AccountId | string | 필수 | 계정 ID |
| LinkId | string | 필수 | 발급 링크 ID. 링크 생성 시 응답으로 받은 token 과 같은 값입니다 — 엔드유저 매칭의 기본 키로 쓰세요. |
| Number | string | 필수 | 개통된 070 번호 |
| SubscriberType | string | 선택 | 가입자 유형 — individual(개인) / corporate(법인) |
| Note | string | 선택 | 링크 생성 시 지정한 메모. 자사 사용자 ID 를 넣어두면 그대로 되돌아옵니다. |
| Timestamp | string | 필수 | 이벤트 발생 시각 (ISO 8601) |
Event=assignment.completed&AccountId=ACxxx&LinkId=FUjxM9qBBy_EIZp7QizzWSqXyUqqmrsnviw7PLdDI5w
&Number=07012340001&SubscriberType=individual&Note=user-42
&Timestamp=2026-08-02T09:12:44.123Z엔드유저의 본인확인 결과(실명·생년월일·CI)는 이 페이로드에 포함되지 않습니다.
본인확인은 ClawOps 가 직접 수행하며 그 결과는 전달하지 않습니다. 엔드유저 매칭은 링크를 만들 때
note 에 자사 사용자 식별자를 넣어두고, 이 이벤트의 LinkId / Note 로 되돌려 받는 방식을 쓰세요.
예제
from flask import Flask, request
app = Flask(__name__)
@app.route("/assignment-webhook", methods=["POST"])
def assignment_webhook():
link_id = request.form.get("LinkId")
number = request.form.get("Number")
note = request.form.get("Note") # 링크 생성 시 넣어둔 자사 사용자 ID
# 발급 대기 상태로 두었던 사용자에게 번호를 연결한다.
activate_user_number(user_id=note, link_id=link_id, number=number)
return "", 204이 요청에도 X-Signature 헤더가 포함됩니다. 서명 검증 가이드를
참고하여 요청의 무결성을 확인하세요.