> For the complete documentation index, see [llms.txt](https://a-send.gitbook.io/api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://a-send.gitbook.io/api/api-reference/reference/webhook.md).
# Webhook
웹훅 수신, 관리 및 결과 알림
## 루틴 웹훅 수신
> 외부 시스템에서 이 엔드포인트로 데이터를 전송하면, 해당 웹훅 코드에 연결된 루틴의 설정에 따라 메시지를 자동 발송합니다.\
> \
> \*\*인증 불필요\*\* — 웹훅 URL 자체가 고유 코드를 포함하므로 별도 인증 없이 호출 가능합니다.\
> \
> \### 동작 흐름\
> 1\. \`code\`에 해당하는 활성 루틴을 조회합니다.\
> 2\. 루틴에 설정된 템플릿 중 가중치 기반으로 하나를 선택합니다.\
> 3\. 루틴의 지연 발송, 예약 시간, 발송 금지 시간 설정을 반영하여 발송 예정 시간을 계산합니다.\
> 4\. 메시지를 발송 큐에 예약합니다.\
> \
> \### 웹훅 URL 확인\
> 루틴 생성 시 반환되는 \`webhook\_url\` 값 또는 루틴 상세 페이지에서 확인할 수 있습니다.
```json
{"openapi":"3.0.3","info":{"title":"Asend API Reference","version":"1.1.0"},"tags":[{"name":"Webhook","description":"웹훅 수신, 관리 및 결과 알림"}],"servers":[{"url":"https://api.a-send.kr","description":"Production"}],"security":[],"paths":{"/webhook/r/{code}":{"post":{"tags":["Webhook"],"summary":"루틴 웹훅 수신","description":"외부 시스템에서 이 엔드포인트로 데이터를 전송하면, 해당 웹훅 코드에 연결된 루틴의 설정에 따라 메시지를 자동 발송합니다.\n\n**인증 불필요** — 웹훅 URL 자체가 고유 코드를 포함하므로 별도 인증 없이 호출 가능합니다.\n\n### 동작 흐름\n1. `code`에 해당하는 활성 루틴을 조회합니다.\n2. 루틴에 설정된 템플릿 중 가중치 기반으로 하나를 선택합니다.\n3. 루틴의 지연 발송, 예약 시간, 발송 금지 시간 설정을 반영하여 발송 예정 시간을 계산합니다.\n4. 메시지를 발송 큐에 예약합니다.\n\n### 웹훅 URL 확인\n루틴 생성 시 반환되는 `webhook_url` 값 또는 루틴 상세 페이지에서 확인할 수 있습니다.\n","operationId":"webhookReceive","parameters":[{"name":"code","in":"path","required":true,"description":"루틴 웹훅 고유 코드 (루틴 생성 시 자동 발급)","schema":{"type":"string","pattern":"^[0-9A-Z]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookReceiveRequest"}}}},"responses":{"202":{"description":"메시지 발송이 예약되었습니다.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendMessageResponse"}}}},"400":{"description":"잘못된 요청","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"유효하지 않은 웹훅 코드","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}}},"500":{"$ref":"#/components/responses/InternalError"}}}}},"components":{"schemas":{"WebhookReceiveRequest":{"type":"object","properties":{"receiver_tel":{"type":"string","description":"수신자 전화번호.\n`to` 필드로도 전달할 수 있습니다. 둘 다 있으면 `receiver_tel`이 우선합니다.\n`010-1234-5678`, `01012345678` 형식 모두 허용됩니다.\n"},"to":{"type":"string","description":"수신자 전화번호 (receiver_tel의 별칭)"},"variables":{"type":"object","nullable":true,"description":"템플릿 변수 (키-값 쌍).\n웹훅에 연결된 템플릿에 `#{변수명}` 형식으로 정의된 변수의 값을 전달합니다.\n","additionalProperties":{"type":"string"}}}},"SendMessageResponse":{"type":"object","properties":{"message":{"type":"string"},"data":{"type":"object","properties":{"message_id":{"type":"string","description":"메시지 예약 고유 ID.\n이 값으로 상태 조회, 취소 등을 할 수 있습니다.\n"}}}}},"ErrorResponse":{"type":"object","properties":{"message":{"type":"string"},"data":{"type":"object","nullable":true,"properties":{"reason":{"type":"string","description":"실패 상세 사유"}}}}},"BaseResponse":{"type":"object","properties":{"message":{"type":"string"},"data":{"nullable":true}}}},"responses":{"InternalError":{"description":"서버 내부 오류","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}}}}}}
```
## 웹훅 목록 조회
> 웹훅 목록을 조회합니다.\
> \
> 웹훅에는 발송 채널, 트리거 조건, 템플릿, 발송 금지 시간, 결과 알림 설정 등이 포함됩니다.
```json
{"openapi":"3.0.3","info":{"title":"Asend API Reference","version":"1.1.0"},"tags":[{"name":"Webhook","description":"웹훅 수신, 관리 및 결과 알림"}],"servers":[{"url":"https://api.a-send.kr","description":"Production"}],"security":[{"HmacAuth":[]}],"components":{"securitySchemes":{"HmacAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"`apiKey={API_KEY}, ts={TIMESTAMP}, nonce={NONCE}, signature={SIGNATURE}` 형식.\n자세한 내용은 Introduction을 참고하세요.\n"}},"schemas":{"WebhookListRequest":{"type":"object","properties":{"cursor":{"type":"string","nullable":true,"description":"페이지네이션 커서"},"limit":{"type":"integer","minimum":1,"maximum":100,"default":20,"description":"한 페이지당 반환할 항목 수 (기본값 20, 최대 100)"},"is_enabled":{"type":"string","nullable":true,"description":"활성/비활성 필터","enum":["Y","N"]}}},"WebhookListResponse":{"type":"object","properties":{"message":{"type":"string"},"data":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/WebhookListItem"}},"next_cursor":{"type":"string","nullable":true,"description":"다음 페이지 커서 (마지막 페이지이면 null)"},"has_more":{"type":"boolean","description":"다음 페이지 존재 여부"}}}}},"WebhookListItem":{"type":"object","properties":{"rid":{"type":"string","description":"루틴 ID"},"name":{"type":"string","description":"루틴 이름"},"is_enabled":{"type":"string","description":"활성 여부 (Y/N)","enum":["Y","N"]},"channel_type":{"type":"string","description":"채널 유형","enum":["kakao","email","sms"]},"store_name":{"type":"string","nullable":true,"description":"연결된 스토어 이름 (웹훅 루틴은 null)"},"job_name":{"type":"string","nullable":true,"description":"트리거 작업 이름 (웹훅 루틴은 null)"},"webhook_code":{"type":"string","nullable":true,"description":"웹훅 트리거 코드 (웹훅 루틴만 존재)"},"block_send_time_start":{"type":"string","nullable":true,"description":"발송 금지 시작 시간 (HH:MM)"},"block_send_time_end":{"type":"string","nullable":true,"description":"발송 금지 종료 시간 (HH:MM)"},"schedule_send_time":{"type":"string","nullable":true,"description":"예약 발송 시간 (HH:MM)"},"rate_send_days":{"type":"integer","description":"지연 발송 일수 (0이면 즉시)"},"result_callback_url":{"type":"string","nullable":true,"description":"발송 결과 수신 웹훅 URL"},"result_callback_method":{"type":"string","nullable":true,"description":"결과 알림 HTTP 메서드","enum":["POST","PUT"]},"created_at":{"type":"string","format":"date-time","description":"생성 시각"}}},"BaseResponse":{"type":"object","properties":{"message":{"type":"string"},"data":{"nullable":true}}}},"headers":{"X-RateLimit-Limit":{"description":"1분당 허용되는 최대 요청 횟수","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"남은 요청 가능 횟수","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"요청 제한이 초기화되는 시간 (Unix Timestamp)","schema":{"type":"integer"}}},"responses":{"Unauthorized":{"description":"인증 실패","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}}},"RateLimitExceeded":{"description":"요청 제한 초과 (1분당 60회)","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}}},"InternalError":{"description":"서버 내부 오류","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}}}}},"paths":{"/v1/webhook/list":{"post":{"tags":["Webhook"],"summary":"웹훅 목록 조회","description":"웹훅 목록을 조회합니다.\n\n웹훅에는 발송 채널, 트리거 조건, 템플릿, 발송 금지 시간, 결과 알림 설정 등이 포함됩니다.\n","operationId":"listWebhooks","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookListRequest"}}}},"responses":{"200":{"description":"조회 성공","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookListResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```
## 웹훅 상세 조회
> 웹훅의 상세 정보를 조회합니다.\
> \
> 응답에 포함된 필드 설명:\
> \
> \| 필드 | 설명 |\
> \|---|---|\
> \| \`block\_send\_time\_start\` / \`block\_send\_time\_end\` | 발송 금지 시간대 (HH:MM). 이 시간대에는 메시지 발송이 보류되며, 금지 시간 종료 후 발송됩니다. |\
> \| \`schedule\_send\_time\` | 예약 발송 시간 (HH:MM). 설정 시 해당 시각에 맞춰 발송됩니다. |\
> \| \`rate\_send\_days\` | 지연 발송 일수. 트리거 발생 후 N일 뒤 발송됩니다. |\
> \| \`result\_callback\_url\` | 발송 결과를 수신할 웹훅 URL. 메시지 발송 완료/실패 시 이 URL로 결과를 POST합니다. |\
> \| \`result\_callback\_method\` | 결과 알림 HTTP 메서드 (\`POST\` 또는 \`PUT\`) |\
> \| \`result\_callback\_headers\` | 결과 알림 요청 시 포함할 커스텀 헤더 (JSON 문자열) |\
> \| \`webhook\_code\` | 웹훅 트리거 루틴의 고유 코드. 웹훅 URL 생성에 사용됩니다. |
```json
{"openapi":"3.0.3","info":{"title":"Asend API Reference","version":"1.1.0"},"tags":[{"name":"Webhook","description":"웹훅 수신, 관리 및 결과 알림"}],"servers":[{"url":"https://api.a-send.kr","description":"Production"}],"security":[{"HmacAuth":[]}],"components":{"securitySchemes":{"HmacAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"`apiKey={API_KEY}, ts={TIMESTAMP}, nonce={NONCE}, signature={SIGNATURE}` 형식.\n자세한 내용은 Introduction을 참고하세요.\n"}},"headers":{"X-RateLimit-Limit":{"description":"1분당 허용되는 최대 요청 횟수","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"남은 요청 가능 횟수","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"요청 제한이 초기화되는 시간 (Unix Timestamp)","schema":{"type":"integer"}}},"schemas":{"WebhookDetailResponse":{"type":"object","properties":{"message":{"type":"string"},"data":{"type":"object","properties":{"rid":{"type":"string","description":"루틴 ID"},"name":{"type":"string","description":"루틴 이름"},"is_enabled":{"type":"string","description":"활성 여부","enum":["Y","N"]},"channel_type":{"type":"string","description":"채널 유형"},"channel_name":{"type":"string","description":"채널 이름"},"store_name":{"type":"string","nullable":true,"description":"연결된 스토어 이름"},"job_name":{"type":"string","nullable":true,"description":"트리거 작업 이름"},"webhook_code":{"type":"string","nullable":true,"description":"웹훅 트리거 코드"},"templates":{"type":"array","description":"연결된 템플릿 목록","items":{"type":"object","properties":{"tid":{"type":"string","description":"템플릿 ID"},"name":{"type":"string","description":"템플릿 이름"},"weight":{"type":"integer","description":"가중치 (복수 템플릿 시 랜덤 선택 비율)"}}}},"block_send_time_start":{"type":"string","nullable":true,"description":"발송 금지 시작 시간 (HH:MM).\n이 시간부터 `block_send_time_end`까지는 메시지 발송이 보류됩니다.\n"},"block_send_time_end":{"type":"string","nullable":true,"description":"발송 금지 종료 시간 (HH:MM).\n금지 시간대에 예정된 메시지는 이 시각 이후로 자동 지연됩니다.\n"},"schedule_send_time":{"type":"string","nullable":true,"description":"예약 발송 시간 (HH:MM).\n설정 시 트리거 발생 시각과 관계없이 해당 시각에 맞춰 발송합니다.\n"},"rate_send_days":{"type":"integer","description":"지연 발송 일수.\n트리거 발생 후 N일 뒤 발송됩니다. 0이면 즉시 발송합니다.\n"},"result_callback_url":{"type":"string","nullable":true,"description":"발송 결과 수신 웹훅 URL.\n메시지 발송 완료 또는 실패 시 이 URL로 결과를 전송합니다.\n"},"result_callback_method":{"type":"string","nullable":true,"description":"결과 알림 HTTP 메서드","enum":["POST","PUT"]},"result_callback_headers":{"type":"string","nullable":true,"description":"결과 알림 요청 시 포함할 커스텀 HTTP 헤더 (JSON 문자열).\n예: `{\"X-Custom-Key\": \"my-secret\", \"Authorization\": \"Bearer token\"}`\n"},"created_at":{"type":"string","format":"date-time","description":"생성 시각"},"updated_at":{"type":"string","format":"date-time","description":"수정 시각"}}}}},"BaseResponse":{"type":"object","properties":{"message":{"type":"string"},"data":{"nullable":true}}}},"responses":{"Unauthorized":{"description":"인증 실패","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}}},"RateLimitExceeded":{"description":"요청 제한 초과 (1분당 60회)","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}}},"InternalError":{"description":"서버 내부 오류","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}}}}},"paths":{"/v1/webhook/detail":{"post":{"tags":["Webhook"],"summary":"웹훅 상세 조회","description":"웹훅의 상세 정보를 조회합니다.\n\n응답에 포함된 필드 설명:\n\n| 필드 | 설명 |\n|---|---|\n| `block_send_time_start` / `block_send_time_end` | 발송 금지 시간대 (HH:MM). 이 시간대에는 메시지 발송이 보류되며, 금지 시간 종료 후 발송됩니다. |\n| `schedule_send_time` | 예약 발송 시간 (HH:MM). 설정 시 해당 시각에 맞춰 발송됩니다. |\n| `rate_send_days` | 지연 발송 일수. 트리거 발생 후 N일 뒤 발송됩니다. |\n| `result_callback_url` | 발송 결과를 수신할 웹훅 URL. 메시지 발송 완료/실패 시 이 URL로 결과를 POST합니다. |\n| `result_callback_method` | 결과 알림 HTTP 메서드 (`POST` 또는 `PUT`) |\n| `result_callback_headers` | 결과 알림 요청 시 포함할 커스텀 헤더 (JSON 문자열) |\n| `webhook_code` | 웹훅 트리거 루틴의 고유 코드. 웹훅 URL 생성에 사용됩니다. |\n","operationId":"getWebhookDetail","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["rid"],"properties":{"rid":{"type":"string","description":"루틴 ID"}}}}}},"responses":{"200":{"description":"조회 성공","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDetailResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"웹훅을 찾을 수 없음","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BaseResponse"}}}},"429":{"$ref":"#/components/responses/RateLimitExceeded"},"500":{"$ref":"#/components/responses/InternalError"}}}}}}
```