인증 Webhook
본인인증(Verify API v2)의 통과·실패·만료를 알리는 verification.* Webhook 을 안내합니다.
인증 Webhook 은 Verify API 로 시작한 인증 한 건의 결과를 알립니다. 계정 레벨에서 REST API 로 등록합니다.
인증번호(코드)는 verification.* 페이로드에 실리지 않습니다. 대조는 ClawOps 가 끝내므로
수신측이 코드를 받아 할 일이 없습니다.
⚠️ 다만 수신형(sms_inbound)은 사용자가 보낸 문자 자체가 고객님의 수신 문자입니다.
그 본문에는 코드가 들어 있고, 원장(messages)에 남고 message.received Webhook 으로도
그대로 전달됩니다 — 인증에 쓰였다고 빼면 받은 문자와 기록이 달라지기 때문입니다.
로그 접근 권한을 그에 맞게 잡아 주세요.
등록
POST /v1/accounts/{accountId}/webhooks
Body:
{
"url": "https://my-app.com/verification-webhook",
"events": ["verification.verified", "verification.failed", "verification.expired"]
}이벤트 종류
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
| verification.verified | event | 선택 | 사용자가 코드를 맞게 입력해 인증이 통과함 |
| verification.failed | event | 선택 | 전달 자체가 실패해 그 건이 failed 로 닫힘 — 문자 발송 실패, 또는 통화 미응답·실패 |
| verification.expired | event | 선택 | ttlSeconds 안에 완료되지 않아 만료됨 |
POST /v2/verifications/{id}/check 는 통과 여부를 곧바로 응답으로 돌려주므로, 발신형
(sms·call)만 쓴다면 Webhook 없이도 결과를 알 수 있습니다. 다만 call 의 미응답은
check 로 알 수 없습니다 — 전화를 받지 않은 건은 verification.failed 로만 통지되므로,
재시도 안내를 띄우려면 등록하는 편이 낫습니다.
수신형(sms_inbound)은 Webhook 이 주 경로입니다. 사용자가 입력할 것이 없어 check 를
부를 수 없기 때문입니다(부르면 422 check_not_supported).
사용자가 문자를 보내지 않은 경우는 verification.expired 가 곧바로 오지 않습니다 —
응답의 instruction.deadline 까지 verification.verified 가 오지 않으면 실패로 처리하십시오.
verification.expired 는 그 건을 조회하는 시점에 확정됩니다.
from 은 문자를 받아 본 적 있는 번호로 지정하시는 편이 안전합니다. 생략하면 계정 번호
중 하나가 자동으로 잡히는데, 갓 발급받은 번호는 수신이 아직 열리지 않았을 수 있습니다.
요청 파라미터
모든 요청은 Content-Type: application/x-www-form-urlencoded POST 입니다.
| 파라미터 | 타입 | 필수 | 설명 |
|---|---|---|---|
| Event | string | 필수 | verification.verified / verification.failed / verification.expired |
| AccountId | string | 필수 | 계정 ID |
| VerificationId | string | 필수 | 인증 건 ID (VE...) |
| Channel | string | 필수 | 인증 방식 — sms, call, sms_inbound |
| To | string | 필수 | 인증 대상 번호 |
| VerifiedAt | string | 선택 | 통과 시각 (ISO 8601). verification.verified 에만 실립니다. |
| Reason | string | 선택 | failed·expired 의 사유 코드. 예: send_failed, ttl_elapsed, call_no-answer, call_busy |
| Timestamp | string | 필수 | 이벤트 발생 시각 (ISO 8601) |
Event=verification.verified&AccountId=ACxxx&VerificationId=VE1a2b3c4d5e6f7a8b
&Channel=sms&To=01012345678&VerifiedAt=2026-09-18T04:00:12.345Z
&Timestamp=2026-09-18T04:00:12.350Z예제
from flask import Flask, request
app = Flask(__name__)
@app.route("/verification-webhook", methods=["POST"])
def verification_webhook():
event = request.form.get("Event")
verification_id = request.form.get("VerificationId")
if event == "verification.verified":
mark_phone_verified(verification_id, request.form.get("To"))
else:
# failed·expired 는 사용자가 다시 시도하게 두면 됩니다.
clear_pending_verification(verification_id)
return "", 204이 요청에도 X-Signature 헤더가 포함됩니다. 서명 검증 가이드를
참고하여 요청의 무결성을 확인하세요.