API 참조: 웹훅

아웃바운드 웹훅은 ProcessMind에서 이벤트가 발생하면 사용자 시스템에 알립니다. 각 전송은 웹훅 비밀 키로 서명된 JSON POST입니다. X-ProcessMind-Signature 헤더에는 sha256=<hex>, 즉 원본 요청 본문의 HMAC-SHA256 값이 포함됩니다. JSON을 파싱하기 전에 수신한 바이트 그대로 서명을 검증하고, 서명이 일치하지 않으면 전송을 거부하세요. 각 본문에는 deliveryId도 포함되어 있어, 최소 한 번 전송되는 이벤트의 중복을 제거하는 데 사용할 수 있습니다.

아웃바운드 웹훅 목록 조회

엔드포인트: GET /v1/tenant/{tenantId}/webhooks

인증: 테넌트 범위 API 키 · read 범위

매개변수:

이름	유형	위치	필수	설명
tenantId	string	경로	예	형식: uuid
limit	integer	쿼리	아니요	반환할 최대 항목 수
offset	integer	쿼리	아니요	건너뛸 항목 수

응답 (200):

웹훅 목록

[
	{
		"id": "00000000-0000-0000-0000-000000000000",
		"url": "string",
		"events": [
			"process.created"
		],
		"description": "string",
		"isActive": true,
		"createdAt": "2024-03-15T16:30:00Z"
	}
]

오류:

• 401 API 키가 없거나 유효하지 않거나 비활성화 또는 만료되었습니다

아웃바운드 웹훅 생성 (서명 비밀 키는 한 번만 반환)

엔드포인트: POST /v1/tenant/{tenantId}/webhooks

인증: 테넌트 범위 API 키 · write 범위

매개변수:

이름	유형	위치	필수	설명
tenantId	string	경로	예	형식: uuid

요청 본문:

{
	"url": "string",
	"events": [
		"process.created"
	],
	"description": "string"
}

필드	유형	필수	설명
url	string	예	서명된 POST 전송을 수신하는 공개 https 엔드포인트 (비공개 주소 또는 루프백 주소는 사용할 수 없음)
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	예	이 웹훅으로 전송을 트리거하는 이벤트
description	string	아니요	선택 입력 항목 최대 길이: 500

응답 (201):

웹훅을 생성했습니다 (서명 비밀 키 포함)

{
	"id": "00000000-0000-0000-0000-000000000000",
	"url": "string",
	"events": [
		"process.created"
	],
	"description": "string",
	"isActive": true,
	"createdAt": "2024-03-15T16:30:00Z",
	"secret": "string"
}

필드	유형	필수	설명
id	string	예	형식: uuid
url	string	예	형식: uri
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	예
description	string	예	최대 길이: 500
isActive	boolean	예	기본값: true
createdAt	string	예	형식: date-time
secret	string	예	서명 비밀 키. 생성 시 이 응답에서만 반환됩니다

오류:

• 400 잘못된 요청: 예를 들어 필터 표현식이 잘못되었거나, 모델이 없는 프로세스이거나, 지원하지 않는 업로드 형식이거나, 필수 필드가 누락된 경우
• 401 API 키가 없거나 유효하지 않거나 비활성화되었거나 만료됨

아웃바운드 webhook 하나 조회

엔드포인트: GET /v1/tenant/{tenantId}/webhooks/{webhookId}

인증: 테넌트 범위 API 키 · read 범위

매개변수:

이름	유형	위치	필수	설명
tenantId	문자열	경로	예	형식: uuid
webhookId	문자열	경로	예	형식: uuid

응답 (200):

Webhook

{
	"id": "00000000-0000-0000-0000-000000000000",
	"url": "string",
	"events": [
		"process.created"
	],
	"description": "string",
	"isActive": true,
	"createdAt": "2024-03-15T16:30:00Z"
}

필드	유형	필수	설명
id	문자열	예	형식: uuid
url	문자열	예	형식: uri
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	예
description	문자열	예	최대 길이: 500
isActive	불리언	예	기본값: true
createdAt	문자열	예	형식: date-time

오류:

• 401 API 키가 없거나 유효하지 않거나 비활성화되었거나 만료됨
• 404 리소스를 찾을 수 없음

아웃바운드 webhook 수정

엔드포인트: PUT /v1/tenant/{tenantId}/webhooks/{webhookId}

인증: 테넌트 범위 API 키 · write 범위

매개변수:

이름	유형	위치	필수	설명
tenantId	문자열	경로	예	형식: uuid
webhookId	문자열	경로	예	형식: uuid

요청 본문:

{
	"url": "string",
	"events": [
		"process.created"
	],
	"description": "string",
	"isActive": true
}

필드	유형	필수	설명
url	문자열	아니요	서명된 POST 요청을 받는 공개 https 엔드포인트
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	아니요	이 webhook으로 전송을 트리거하는 이벤트
description	문자열	아니요	선택 사항인 설명 최대 길이: 500
isActive	불리언	아니요	webhook 활성화 여부

응답 (200):

Webhook이 수정되었습니다

{
	"id": "00000000-0000-0000-0000-000000000000",
	"url": "string",
	"events": [
		"process.created"
	],
	"description": "string",
	"isActive": true,
	"createdAt": "2024-03-15T16:30:00Z"
}

필드	유형	필수	설명
id	문자열	예	형식: uuid
url	문자열	예	형식: uri
events	process.created | process.updated | process.deleted | mapping.created | data.ready | simulation.completed | webhook.test[]	예
description	문자열	예	최대 길이: 500
isActive	불리언	예	기본값: true
createdAt	문자열	예	형식: date-time

오류:

• 401 API 키가 없거나 유효하지 않거나 비활성화되었거나 만료됨
• 404 리소스를 찾을 수 없음

아웃바운드 webhook 삭제

엔드포인트: DELETE /v1/tenant/{tenantId}/webhooks/{webhookId}

인증: 테넌트 범위 API 키 · write 범위

매개변수:

이름	유형	위치	필수	설명
tenantId	문자열	경로	예	형식: uuid
webhookId	문자열	경로	예	형식: uuid

응답 (200):

Webhook이 삭제되었습니다

{
	"deleted": true
}

필드	유형	필수	설명
deleted	불리언	예

오류:

• 401 API 키가 없거나 유효하지 않거나 비활성화되었거나 만료됨
• 404 리소스를 찾을 수 없음

Webhook으로 테스트 전송 트리거하기

엔드포인트: POST /v1/tenant/{tenantId}/webhooks/{webhookId}/test

인증: 테넌트 범위 API 키 · write 범위

매개변수:

이름	유형	위치	필수	설명
tenantId	문자열	경로	예	형식: uuid
webhookId	문자열	경로	예	형식: uuid

응답 (200):

테스트 전송을 트리거했습니다

{
	"message": "string"
}

필드	유형	필수	설명
message	문자열	예

오류:

• 401 API 키가 없거나 유효하지 않거나 비활성화되었거나 만료됨
• 404 리소스를 찾을 수 없음