# 관리번호 Webhook (/docs/webhooks/assignment)

관리번호 Webhook 은 [관리번호 발급 링크](/docs/api-reference/assignment-links)를 통해 엔드유저가
본인인증을 완료하고 **번호가 실제로 개통된 직후** 전송됩니다. 계정 레벨에서 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.released"]
}
```

## 이벤트 종류

- `assignment.completed` (event, 선택): 엔드유저가 본인인증·약관동의를 마치고 070번호가 본인 명의로 개통 완료됨
- `assignment.released` (event, 선택): 관리번호가 회수됨. 회수 후 최대 5분 안에 전송됩니다.

링크가 만료(`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)는 이 페이로드에 포함되지 않습니다.**
본인확인은 한국AI통신이 직접 수행하며 그 결과는 전달하지 않습니다. 엔드유저 매칭은 링크를 만들 때
`note` 에 자사 사용자 식별자를 넣어두고, 이 이벤트의 `LinkId` / `Note` 로 되돌려 받는 방식을 쓰세요.

## assignment.released

관리번호가 회수되면 전송됩니다. 회수 사유는 `Reason` 으로 옵니다.

- `Event` (string, 필수): 고정값 assignment.released
- `AccountId` (string, 필수): 계정 ID
- `LinkId` (string, 필수): 이 번호를 개통한 발급 링크 ID
- `Number` (string, 필수): 회수된 070 번호
- `Note` (string, 선택): 링크 생성 시 지정한 메모
- `Reason` (string, 필수): released(API·콘솔에서 반납) / addon_disabled(관리번호 추가 종료) / subscription_ended(구독 종료·결제 실패) / account_deleted(계정 삭제) / other
- `ReleasedAt` (string, 필수): 회수 시각 (ISO 8601)
- `Timestamp` (string, 필수): 이벤트 전송 시각 (ISO 8601)


```
Event=assignment.released&AccountId=ACxxx&LinkId=FUjxM9qBBy_EIZp7QizzWSqXyUqqmrsnviw7PLdDI5w
&Number=07012340001&Note=user-42&Reason=released
&ReleasedAt=2026-10-28T09:12:44.123Z&Timestamp=2026-10-28T09:15:01.002Z
```

## 예제

```python
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` 헤더가 포함됩니다. [서명 검증 가이드](/docs/webhooks/signature-verification)를
참고하여 요청의 무결성을 확인하세요.