외부 이벤트 모니터 이벤트 수신¶
POST /api/v1/push-events/{secret}/{subUri}
개요¶
구성된 외부 이벤트 Webhook을 통해 단일 비즈니스 이벤트를 수신합니다.
호출 전 및 사용 단계¶
먼저 jsonScript.type=OuterEventChecker인 모니터를 생성하고 활성화한 뒤, 신뢰할 수 있는 상세 정보에서 secret 및 subUri를 가져와 해당 전용 Webhook으로 보고합니다. 이 엔드포인트는 requireSignIn=false이며 DF-API-KEY를 검증하지 않습니다. URL의 secret은 위치 식별/접근 역할을 하므로 자격 증명처럼 보관해야 하며 실제 주소를 공개해서는 안 됩니다. subUri는 단일 경로 세그먼트여야 하고 /를 포함할 수 없으며, 슬래시를 %2F로 작성해도 현재 공개 라우트와 일치하지 않습니다. 새 구성에는 datakit-push와 같은 간단한 값을 권장합니다.
일치하지 않는다고 해서 조용히 무시되는 것은 아닙니다. secret을 알 수 없으면 일반적으로 404가 반환되고, 접미사가 일치하지 않거나 규칙이 비활성화된 경우에는 해당 비즈니스 오류가 반환됩니다. 워크스페이스가 잠긴 경우에도 거부되며, 잠금 상태는 최대 약 10분 동안 캐시될 수 있습니다. event의 고정 필드 이외의 사용자 정의 필드는 문자열만 가능하며, 디멘션, 이미 바인딩된 key:value 태그 키 또는 예약 필드를 덮어쓸 수 없습니다. extraData에는 보조 JSON을 별도로 담습니다.
검증을 통과하면 동기적으로 이벤트 처리 서비스를 호출하여 모니터/그룹/태그 및 채널 컨텍스트를 다운스트림에 함께 전달합니다. 규칙의 isChangeEvent=true인 경우 변경 이벤트 소스로 처리합니다. 성공 응답은 다운스트림 함수 결과를 그대로 감쌉니다. SDK는 HTTP 상태만으로 실패를 일괄 판단하지 않으며, 객체가 아니면서 200이 아니거나 명시적 ok=false인 경우 일반적으로 ft.OuterFuncFailed로 전환됩니다. 반면 객체의 ok가 false가 아닌 경우 업스트림 5xx에서도 최상위 HTTP 200이 반환될 수 있으므로 content의 비즈니스 결과를 반드시 확인해야 합니다. 여기서 이벤트가 모든 조회/알림 페이지에 표시된다는 점을 보장하지 않으며, 이벤트 전역 고유 ID나 멱등 자격 증명도 반환하지 않습니다. 이 API에는 biz_ticket 등의 필드를 기반으로 한 중복 제거 보장이 없으므로, 타임아웃 후에는 이벤트가 이미 생성되었는지 먼저 조회한 뒤 재시도 여부를 결정해야 합니다. OpenAPI의 이 라우트는 AIAPI의 추가 호출 감사 컨텍스트 처리를 수행하지 않습니다.
라우트 매개변수¶
| 매개변수명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| secret | string | Y | 필수 경로 세그먼트이며 DF-API-KEY가 아닙니다. 저장된 삭제되지 않은 규칙과 정확히 일치해야 합니다. 예: SECRET-PLACEHOLDER가져오기 또는 입력 방법: 대상 외부 이벤트 모니터 상세 정보의 secret에서 가져옵니다. |
| subUri | string | Y | 필수 단일 경로 세그먼트이며 대소문자를 정확히 구분하고 슬래시를 포함하지 않습니다. 여러 단계의 URL을 직접 조합하지 않습니다. 예: datakit-push가져오기 또는 입력 방법: 동일한 규칙의 jsonScript.subUri에서 가져옵니다. |
Body 요청 매개변수¶
| 매개변수명 | 유형 | 필수 | 설명 |
|---|---|---|---|
| event.status | string | 필수입니다. 프로토콜 소문자를 사용하며 errorEvent/nodata로 대체할 수 없습니다. 예: warning가져오기 또는 입력 방법: fatal/critical/error/warning/info/ok 중에서 해당 비즈니스 상태를 선택합니다. |
|
| event.date | integer | 선택 사항이며 밀리초/마이크로초가 아닙니다. 생략하면 그대로 다운스트림에 전달하지 않으며 이벤트 시간은 다운스트림에서 결정합니다. 클라이언트가 미래/비정상 시간을 사용할 수 있음을 보장하지 않습니다. 예: 1785427200가져오기 또는 입력 방법: 외부 이벤트의 실제 발생 시간을 Unix 초 정수로 변환합니다. |
|
| event.title | string | 선택적 문자열입니다. 생략하면 Studio에서 고정 제목을 보충하지 않으며 최종적으로 수신 서비스 프로토콜에 따라 처리됩니다. 예: 生产服务异常가져오기 또는 입력 방법: 비즈니스 알림 제목에서 가져옵니다. |
|
| event.message | string | 선택적 문자열이며 JSON 배열이 아닙니다. 비밀 키를 포함하지 마십시오. 예: 健康检查返回错误。가져오기 또는 입력 방법: 외부 감지 결과에서 이벤트를 식별할 수 있는 내용을 입력합니다. |
|
| event.dimension_tags | json | 선택적 객체이며 디멘션 키는 _ 또는 df_로 시작할 수 없습니다. 이 계층에서는 객체 및 키만 검사하며, 값은 이벤트 디멘션에 사용할 수 있는 단순 데이터 유형을 선택해야 하고 사용자 정의 최상위 동일 이름 필드로 중복할 수 없습니다. 예: {"host": "web-example", "service": "production"}가져오기 또는 입력 방법: 이 이벤트의 실제 호스트/서비스 등 디멘션 필드 및 값을 선택합니다. |
|
| event.dimension_tags.디멘션 이름 | any | 동적 디멘션 값이며 태그 이름 배열이 아닙니다. 키는 사용자 정의 최상위 필드와 이름이 중복될 수 없습니다. 예: web-example가져오기 또는 입력 방법: 예를 들어 host는 외부 시스템의 해당 리소스 식별자에서 가져옵니다. |
|
| event.check_value | float | 선택적 부동 소수점/숫자이며 문자열로 전달하지 않습니다. 단위는 외부 감지에서 정의하며 Studio는 환산하지 않습니다. 예: 12.5가져오기 또는 입력 방법: 외부의 실제 감지 수치에서 가져옵니다. |
|
| event.비즈니스 필드 | string | 선택적 사용자 정의 최상위 필드이며 값은 반드시 문자열이어야 합니다. biz_/ext_ 접두사를 권장하며, 키는 _/df_로 시작할 수 없고 dimension_tags 키 또는 이미 바인딩된 콜론 태그의 키와 중복될 수 없으며 예약 필드도 사용할 수 없습니다. 예: ticket-example가져오기 또는 입력 방법: 예를 들어 biz_ticket은 외부 티켓 또는 요청 식별자에서 가져옵니다. |
|
| extraData.사용자 정의 키 | any | 동적 JSON 값이며 대상 이벤트 데이터 프로토콜을 따릅니다. 예: healthcheck가져오기 또는 입력 방법: 통합 측의 실제 메타 정보에 따라 정의합니다. |
|
| event | json | Y | 필수 JSON 객체이며 이벤트 배열이 아닙니다. status는 조건부 필수입니다. 여기서는 이미 존재하는 외부 감지 결과만 수신하며 임계값 조회를 수행하지 않습니다. null 허용: False 예: {"date": 1785427200, "status": "warning", "title": "生产服务异常", "message": "健康检查返回错误。", "dimension_tags": {"host": "web-example", "service": "production"}, "check_value": 12.5, "biz_ticket": "ticket-example"}가져오기 또는 입력 방법: 비즈니스 시스템/알림 플랫폼의 실제 감지 결과에서 하나의 이벤트 객체를 구성합니다. |
| extraData | json | 선택적 JSON 객체로 기본값은 {}이며, 다운스트림 이벤트의 df_meta.extra_data로 사용됩니다. event 최상위 필드를 대체하지 않습니다. 통일된 필수 하위 키가 없으며 자격 증명을 넣지 마십시오. null 허용: False 예: {"source_system": "healthcheck", "request_id": "request-example"}가져오기 또는 입력 방법: 외부 연동에서 보조 식별 필드를 가져옵니다. 예: 소스 시스템 및 외부 요청 ID. |
매개변수 추가 설명¶
매개변수 설명:
body 요청 매개변수 본문 구조 설명
| 매개변수명 | 매개변수 유형 | 필수 여부 | 매개변수 설명 |
|---|---|---|---|
| event | json | 예 | 이벤트 데이터 |
| extraData | json | 아니요 | 추가 데이터로 최종적으로 이벤트의 df_meta.extra_data 필드에 추가됩니다. key:value 형식이면 됩니다. |
event 요청 매개변수 본문 구조 설명
| 매개변수명 | 매개변수 유형 | 필수 여부 | 매개변수 설명 |
|---|---|---|---|
| date | int | 아니요 | 이벤트 시간(단위: 초) |
| status | string | 예 | 이벤트 상태, 선택 가능: fatal, critical, error, warning, info, ok |
| title | string | 아니요 | 이벤트 제목 |
| message | string | 아니요 | 이벤트 내용 |
| dimension_tags | json | 아니요 | 디멘션 태그, 예: |
| check_value | float | 아니요 | 검사 값 |
| 사용자 정의 필드 | str | 아니요 | 2024-09-04 사용자 정의 필드로, 이벤트 최상위 필드로 사용되며 제한 조건을 충족해야 합니다. |
event.{사용자 정의 필드} 제한 조건 설명
동일한 이름의 필드가 서로 다른 유형으로 보고되어 이후 문제가 발생하는 것을 방지하기 위해 사용자 정의 필드는 다음 제한 조건을 충족해야 합니다:
- 필드 값은 문자열 유형이어야 합니다(예: "abc", "123").
- 필드 이름은 밑줄 _ 또는 df_로 시작할 수 없습니다.
- 필드 이름은 dimension_tags에서 분해된 필드 이름, labels에서 분해된 필드 이름과 중복될 수 없습니다.
- 필드 이름은 다음 예약 필드를 사용할 수 없습니다(사용자 정의 필드는 모두 ext_xxx, biz_xxx 등과 같이 직접 정의한 접두사로 시작하여 구분하는 것을 권장합니다):
- date
- status
- source
- title
- message
- dimension_tags
- check_value
- time
- time_us
- timestamp
- workspace_uuid
- workspace_name
- extra_data
- create_time
요청 예시¶
curl --request POST 'https://openapi.guance.com/api/v1/push-events/SECRET-PLACEHOLDER/datakit-push' \
-H 'Content-Type: application/json' \
--data-raw '{"event":{"date":1785427200,"status":"warning","title":"生产服务异常","message":"健康检查返回错误。","dimension_tags":{"host":"web-example","service":"production"},"check_value":12.5,"biz_ticket":"ticket-example"},"extraData":{"source_system":"healthcheck","request_id":"request-example"}}'
응답¶
HTTP 200, application/json입니다. 아래 예시는 바로 읽을 수 있는 주요 필드를 보여줍니다.
| 필드 | 유형 | 설명 |
|---|---|---|
| content | object 또는 기타 JSON | 다운스트림 함수 결과를 그대로 감쌉니다. 아래는 기존의 일반적인 응답 필드이며 버전에 따라 필드가 생략될 수 있습니다. |
| content.data | JSON | 다운스트림 비즈니스 결과로 일반적으로 {}입니다. 이벤트 ID가 고정적으로 포함되지는 않습니다. |
| content.error | integer 또는 string | 다운스트림 비즈니스 결과 코드입니다. 예: 200이며 Studio의 HTTP 상태가 아닙니다. |
| content.message | string | 다운스트림 비즈니스 메시지입니다. |
| content.ok | boolean | 다운스트림 함수 결과 표시입니다. 명시적 false는 일반적으로 SDK에서 ft.OuterFuncFailed로 변환됩니다. |
| content.reqCost | number | 다운스트림 원본 소요 시간 통계 값입니다. Studio는 단위를 정규화하지 않으며 생략될 수 있습니다. |
| content.reqTime | string | 다운스트림 요청 시간입니다. 일반적으로 ISO8601 UTC 문자열이며 생략될 수 있습니다. |
| content.respTime | string | 다운스트림 응답 시간입니다. 일반적으로 ISO8601 UTC 문자열이며 생략될 수 있습니다. |
| content.traceId | string | 다운스트림 실행 추적 식별자로, 최상위 Studio traceId와 다를 수 있습니다. |
| content.declaration | object | 비어 있지 않은 객체에만 공통 선언이 추가되며 다른 응답 형태에서는 생략될 수 있습니다. |
{
"code": 200,
"content": {
"data": {},
"error": 200,
"message": "",
"ok": true,
"reqCost": 458,
"reqTime": "2026-07-30T16:00:00.000Z",
"respTime": "2026-07-30T16:00:00.458Z",
"traceId": "FUNC-TRACE-EXAMPLE",
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
오류 응답¶
인증, 속도 제한 및 공통 요청 오류는 공통 오류 정의를 참조하십시오.
이 Webhook 엔드포인트는 DF-API-KEY 인증을 수행하지 않습니다. API Key 누락/권한 오류는 이 페이지의 주요 연동 경로로 간주해서는 안 됩니다. 이벤트 검증, 규칙/워크스페이스 상태 및 다운스트림 비즈니스 오류는 이 페이지에서 확인하십시오. 슬래시를 포함한 subUri는 라우트와 일치할 수 없으며, 바로 404가 반환될 수 있고 통일된 JSON 오류 래퍼를 보장하지 않습니다.
| HTTP 상태 | errorCode | 발생 조건 | 메시지 또는 응답 설명 | 처리 방법 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | 요청 필드가 누락되었거나 필드 값이 선언된 검증 조건을 위반했습니다 | 매개변수 파싱 실패 | 매개변수 위치, 필드 이름, 유형 및 값을 확인하십시오. |
| 400 | ft.RequestJsonFormatError | 요청 JSON 구문이 유효하지 않음 | 요청 JSON 형식 오류 | content.reason, line, column에 따라 JSON을 수정하십시오. |
| 400 | ft.JsonFormatError | JSON Body 최상위가 객체가 아님(예: 배열/문자열) | 일부 json 파일 형식 오류 | 예시에 따라 JSON 객체를 제출해야 하며 checkers 또는 event 배열을 직접 제출할 수 없습니다. |
| 400 | ft.ParamsValidateError | event 객체 내 status 누락/유효하지 않음, date/check_value/title 등 고정 하위 필드 유형 불일치 | 매개변수 검증 실패: {} | 이 페이지의 단일 이벤트 객체 및 필드 유형에 따라 제출하십시오. |
| 404 | ft.NotFoundRuleInspector | secret에 대응하는 삭제되지 않은 규칙이 없거나 소속 워크스페이스를 사용할 수 없음 | 지정된 규칙/검사기를 찾을 수 없음 | 이미 생성한 외부 이벤트 모니터 상세 정보에서 Webhook 주소를 다시 가져오고 API Key를 secret으로 사용하지 마십시오. |
| 403 | ft.WorkspaceIsLocked | 대상 워크스페이스가 잠겨 있거나 단기 잠금 캐시가 아직 유효함 | 워크스페이스가 잠겨 있어 작업할 수 없습니다 | 관리자가 잠금 해제 상태를 확인하고, 캐시가 최대 약 10분 유지된 후 다시 시도하십시오. |
| 406 | ft.OuterEventCheckerWebhookSubUriNotValid | 경로 subUri가 해당 규칙에 저장된 값과 다름 | 외부 이벤트 모니터의 webhook 주소가 유효하지 않습니다. 주소가 올바른지 확인하십시오 | 신뢰할 수 있는 상세 정보의 전체 Webhook 접미사에 따라 호출하고 대소문자와 경로 세그먼트에 주의하십시오. |
| 406 | ft.OuterEventCheckerNotAvailable | 규칙이 현재 status=0이 아님(예: 비활성화됨) | 외부 이벤트 모니터가 비활성화되었거나 삭제되었습니다 | 비즈니스에서 허용됨을 확인한 후 권한이 있는 사용자가 활성화한 뒤 다시 보고하십시오. 규칙 삭제 시 일반적으로 먼저 존재하지 않음이 반환됩니다. |
| 404 | ft.MonitorNotFound | 규칙과 연결된 그룹이 존재하지 않거나 삭제됨 | 규칙 그룹을 찾을 수 없음 | 관리자가 과거 규칙 그룹 연결을 확인한 후 수정하십시오. |
| 400 | ft.DimensionTagsStartswithError | 디멘션 키가 _ 또는 df_로 시작함 | dimension_tags key는 df_, _로 시작할 수 없습니다 | 정상적인 비즈니스 디멘션 키로 변경하십시오. |
| 400 | ft.CustomEventFieldValueTypeError | 사용자 정의 최상위 필드 값이 문자열이 아님 | 사용자 정의 필드 값은 문자열이어야 합니다 | 약속된 문자열로 변환하고 숫자 검사 값은 check_value에 넣으십시오. |
| 400 | ft.CustomEventFieldStartswithError | 사용자 정의 최상위 키가 _ 또는 df_로 시작함 | 사용자 정의 필드는 df_, _로 시작할 수 없습니다 | biz_/ext_ 비즈니스 접두사를 사용하십시오. |
| 400 | ft.CustomEventFieldWithDimensionTagsNotAllowed | 사용자 정의 최상위 키가 dimension_tags 키와 같음 | 사용자 정의 필드 이름은 dimension_tags의 key를 사용할 수 없습니다 | 한 위치만 유지하거나 비즈니스 필드 이름을 변경하십시오. |
| 400 | ft.CustomEventFieldLabelKeyNotAllowed | 사용자 정의 필드가 규칙에 바인딩된 key:value 태그의 key와 중복됨 | 사용자 정의 필드 이름은 해당 모니터의 태그(key:value) 중 key를 사용할 수 없습니다 | 바인딩된 태그를 확인하고 비즈니스 필드 이름을 변경하십시오. |
| 400 | ft.CustomEventFieldNotAllowed | 사용자 정의 키가 예약 필드 source/time/time_us/timestamp/workspace_uuid/workspace_name/extra_data/create_time을 사용함 | 사용자 정의 필드 이름은 예약 필드를 사용할 수 없습니다 | 비즈니스 접두사를 사용하고 고정 필드는 이 페이지에 규정된 위치에 제출하십시오. |
| 400 | ft.OuterFuncFailed | 이벤트 처리 함수가 ok=false 또는 JSON이 아닌 실패 결과를 반환함 | 외부 함수 호출 실패 | 오류 message와 traceId를 기반으로 다운스트림 처리를 파악하고, 이미 수신되었는지 확인한 후 재시도하십시오. |
| 500 | ft.InternalServerError | 다운스트림 타임아웃/연결/유효하지 않은 JSON 등 포착되지 않은 예외, 캐시/스토리지 또는 응답 처리 실패 | 내부 오류 | 먼저 외부 요청 식별자로 이벤트가 이미 생성되었는지 조회하여 무작정 재전송으로 인한 중복을 피하고 traceId를 제공하십시오. |