PATCH/v1/webhooks/{webhook_id}

웹훅 수정

update_webhook

수신 주소, 설명, 구독, 접근 범위, 필터, 사용자 지정 헤더, 발신 인증, 활성화 상태를 변경해요. active: true이면 웹훅을 활성화하고 일시 중지를 풀어, 쌓인 전송이 순서대로 나가요. active: false이면 웹훅을 비활성화하고 대기 중인 전송을 취소해요. headers 값은 사용자 지정 헤더 목록 전체를 교체하며, value 값이 없는 항목은 같은 이름 헤더의 이전 값을 유지해요. auth: null, data_profile_id: null은 각각 발신 인증과 데이터 프로필을 제거해요.

인증

Authorization 헤더로 API 키를 보내세요: Authorization: Bearer <키>.

경로 파라미터

webhook_idinteger필수

헤더 파라미터

Idempotency-Keystring
쓰기 요청을 안전하게 재시도하기 위한 키예요. 출력 가능한 ASCII 문자 1~255자이며, 논리적 처리 단위마다 UUID v4를 하나씩 쓰기를 권장해요. 24시간 안에 같은 키로 재시도하면 처리를 다시 실행하지 않고, 저장된 응답(상태, 헤더, 본문)을 Idempotency-Replayed: true 헤더와 함께 반환해요. 같은 키를 다른 메서드, 경로, Content-Type 값이나 본문과 함께 보내면 409 api.idempotency_mismatch 오류를 반환하고, 첫 요청이 아직 실행 중이면 409 api.idempotency_in_progress 오류를 Retry-After: 1 헤더와 함께 반환해요. 5xx나 429 응답 뒤에는 키가 해제되어, 재시도하면 처리가 다시 실행돼요. 키의 적용 범위는 조직과 호출자(API 키, 사용자, 사용자 지정 소스 키)예요.
length ≥ 1, length ≤ 255

요청 본문

application/json

객체: WebhookUpdate

urlstring | null
length ≤ 2048
descriptionstring | null
length ≤ 200
eventsarray of WebhookEventFilter | null
items ≥ 1
activeboolean | null
rolestring | null
허용 값: admineditorviewernull
data_profile_idinteger | null
null이면 데이터 프로필을 제거해요.
collection_idsarray of integer | null
웹훅의 컬렉션. 빈 목록은 역할과 데이터 프로필로 볼 수 있는 모든 컬렉션을 뜻하고, 값이 없거나 null이면 그대로 유지돼요. 키 자체가 컬렉션으로 제한되어 있으면 컬렉션이 모두 그 키의 목록 안에 있는 웹훅만 보고 바꿀 수 있어요(다른 웹훅은 404 webhooks.not_found 오류를 반환해요). 빈 목록이나 그 키의 목록 밖에 있는 컬렉션을 보내면 403 webhooks.collections_outside_key 오류를 반환해요.
items ≤ 200
tagsarray of string | null
items ≤ 50
payloadstring | null
허용 값: fullthinnull
headersarray of WebhookHeaderInput | null
items ≤ 10
authWebhookAuthInput | null
null이면 발신 인증을 제거해요.

응답

200성공 응답

응답 헤더

RateLimit-Policy
적용 중인 한도. IETF 초안 draft-ietf-httpapi-ratelimit-headers 형식이며, 쉼표로 구분한 "<name>";q=<quota>;w=<window in seconds> 항목으로 이루어져요. key 항목은 API 키의 요청 속도예요(할당량은 버스트, 시간 창은 버스트가 완전히 다시 채워지는 시간이에요. 세션에서는 user, 자격 증명이 없으면 ip예요). minute, day, month 항목은 UTC 기준 달력상의 분, 일, 월에 대한 조직의 할당량이에요.
RateLimit
RateLimit-Policy 헤더의 각 한도에서 남은 양: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy 헤더에서 가장 엄격한 항목(남은 요청 수가 가장 적은 항목)의 한도.
X-RateLimit-Remaining
가장 엄격한 한도에서 남은 요청 수.
X-RateLimit-Reset
가장 엄격한 한도가 초기화될 때까지 남은 초.
Idempotency-Replayed
true이면 이 Idempotency-Key 값으로 저장된 응답을 재생한 것이에요. 처리는 다시 실행되지 않았어요.

application/json

객체: WebhookEndpoint

idinteger필수
urlstring필수
descriptionstring필수
eventsarray of WebhookEventFilter필수
activeboolean필수
statusWebhookStatus필수
paused_atstring (date-time) | null
paused_reasonstring | null
failures: 연속 10번의 전송 시도 실패, feature_disabled: 요금제에 웹훅이 포함되지 않음.
disabled_reasonstring | null
gone: 수신 서버가 410으로 응답함, manual: 관리자가 비활성화함.
허용 값: gonemanualnull
disabled_atstring (date-time) | null
roleWebhookRole필수
data_profile_idinteger | null
웹훅의 데이터 프로필(null이면 같은 역할의 API 키처럼 프로필 없음).
collection_idsarray of integer필수
웹훅이 이벤트를 받는 컬렉션. 비어 있으면 역할과 데이터 프로필로 접근할 수 있는 모든 컬렉션이에요.
tagsarray of string필수
이 태그 중 하나라도 있는 카드의 카드 이벤트만 받아요. 비어 있으면 필터가 없어요.
payloadWebhookPayloadMode필수
headersarray of WebhookHeader필수
auth_typestring | null
발신 인증의 유형(null이면 없음).
허용 값: bearerbasicnull
auth_setboolean필수
발신 인증이 설정되었는지 여부(값은 반환되지 않아요).
previous_secret_valid_untilstring (date-time) | null
이전 시크릿으로도 전송에 서명하는 기한(null이면 유예 기간이 없어요).
healthWebhookHealth
consecutive_failuresinteger필수
last_delivery_atstring (date-time) | null
last_success_atstring (date-time) | null
last_errorstring | null
created_byinteger | null
created_by_namestring | null
created_atstring (date-time)필수
updated_atstring (date-time)필수

400잘못된 요청이에요. 파라미터 값이나 객체의 상태 때문에 이 동작을 할 수 없어요(`detail` 필드에 메시지가 있어요).

응답 헤더

RateLimit-Policy
적용 중인 한도. IETF 초안 draft-ietf-httpapi-ratelimit-headers 형식이며, 쉼표로 구분한 "<name>";q=<quota>;w=<window in seconds> 항목으로 이루어져요. key 항목은 API 키의 요청 속도예요(할당량은 버스트, 시간 창은 버스트가 완전히 다시 채워지는 시간이에요. 세션에서는 user, 자격 증명이 없으면 ip예요). minute, day, month 항목은 UTC 기준 달력상의 분, 일, 월에 대한 조직의 할당량이에요.
RateLimit
RateLimit-Policy 헤더의 각 한도에서 남은 양: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy 헤더에서 가장 엄격한 항목(남은 요청 수가 가장 적은 항목)의 한도.
X-RateLimit-Remaining
가장 엄격한 한도에서 남은 요청 수.
X-RateLimit-Reset
가장 엄격한 한도가 초기화될 때까지 남은 초.

application/json

객체: Error

401자격 증명(세션 쿠키나 API 키)을 보내지 않았거나 키를 찾을 수 없어요.

응답 헤더

RateLimit-Policy
적용 중인 한도. IETF 초안 draft-ietf-httpapi-ratelimit-headers 형식이며, 쉼표로 구분한 "<name>";q=<quota>;w=<window in seconds> 항목으로 이루어져요. key 항목은 API 키의 요청 속도예요(할당량은 버스트, 시간 창은 버스트가 완전히 다시 채워지는 시간이에요. 세션에서는 user, 자격 증명이 없으면 ip예요). minute, day, month 항목은 UTC 기준 달력상의 분, 일, 월에 대한 조직의 할당량이에요.
RateLimit
RateLimit-Policy 헤더의 각 한도에서 남은 양: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy 헤더에서 가장 엄격한 항목(남은 요청 수가 가장 적은 항목)의 한도.
X-RateLimit-Remaining
가장 엄격한 한도에서 남은 요청 수.
X-RateLimit-Reset
가장 엄격한 한도가 초기화될 때까지 남은 초.

application/json

객체: Error

403이 동작은 허용되지 않아요. 역할이 부족하거나, 컬렉션이나 카드에 접근할 수 없거나, 요청이 “View as” 모드로 실행 중이거나, 조직이 정지 또는 삭제된 경우예요(`detail` 필드는 `code: org_suspended | org_deleted` 값을 가진 객체예요).

응답 헤더

RateLimit-Policy
적용 중인 한도. IETF 초안 draft-ietf-httpapi-ratelimit-headers 형식이며, 쉼표로 구분한 "<name>";q=<quota>;w=<window in seconds> 항목으로 이루어져요. key 항목은 API 키의 요청 속도예요(할당량은 버스트, 시간 창은 버스트가 완전히 다시 채워지는 시간이에요. 세션에서는 user, 자격 증명이 없으면 ip예요). minute, day, month 항목은 UTC 기준 달력상의 분, 일, 월에 대한 조직의 할당량이에요.
RateLimit
RateLimit-Policy 헤더의 각 한도에서 남은 양: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy 헤더에서 가장 엄격한 항목(남은 요청 수가 가장 적은 항목)의 한도.
X-RateLimit-Remaining
가장 엄격한 한도에서 남은 요청 수.
X-RateLimit-Reset
가장 엄격한 한도가 초기화될 때까지 남은 초.

application/json

객체: Error

404객체가 없거나 접근할 수 없어요. API는 접근이 제한된 객체가 존재하는지 확인해 주지 않아요.

응답 헤더

RateLimit-Policy
적용 중인 한도. IETF 초안 draft-ietf-httpapi-ratelimit-headers 형식이며, 쉼표로 구분한 "<name>";q=<quota>;w=<window in seconds> 항목으로 이루어져요. key 항목은 API 키의 요청 속도예요(할당량은 버스트, 시간 창은 버스트가 완전히 다시 채워지는 시간이에요. 세션에서는 user, 자격 증명이 없으면 ip예요). minute, day, month 항목은 UTC 기준 달력상의 분, 일, 월에 대한 조직의 할당량이에요.
RateLimit
RateLimit-Policy 헤더의 각 한도에서 남은 양: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy 헤더에서 가장 엄격한 항목(남은 요청 수가 가장 적은 항목)의 한도.
X-RateLimit-Remaining
가장 엄격한 한도에서 남은 요청 수.
X-RateLimit-Reset
가장 엄격한 한도가 초기화될 때까지 남은 초.

application/json

객체: Error

422유효성 검사 오류예요. 본문이나 파라미터가 스키마와 맞지 않거나(`detail` 필드는 유효성 검사 오류 목록), 파라미터 값이 허용 범위를 벗어났어요(`detail` 필드는 메시지).

응답 헤더

RateLimit-Policy
적용 중인 한도. IETF 초안 draft-ietf-httpapi-ratelimit-headers 형식이며, 쉼표로 구분한 "<name>";q=<quota>;w=<window in seconds> 항목으로 이루어져요. key 항목은 API 키의 요청 속도예요(할당량은 버스트, 시간 창은 버스트가 완전히 다시 채워지는 시간이에요. 세션에서는 user, 자격 증명이 없으면 ip예요). minute, day, month 항목은 UTC 기준 달력상의 분, 일, 월에 대한 조직의 할당량이에요.
RateLimit
RateLimit-Policy 헤더의 각 한도에서 남은 양: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy 헤더에서 가장 엄격한 항목(남은 요청 수가 가장 적은 항목)의 한도.
X-RateLimit-Remaining
가장 엄격한 한도에서 남은 요청 수.
X-RateLimit-Reset
가장 엄격한 한도가 초기화될 때까지 남은 초.

application/json

객체: Error

429요청이 너무 많거나(`api.rate_limited`), 조직의 분·일·월 할당량을 다 썼거나(`api.quota_exceeded`, `error.details` 필드에 `quota`, `limit`, `reset_at` 값이 있어요), 조직의 한도에 도달했거나, 답변 서비스가 바쁜 상태예요(`answers.engine_busy`). `Retry-After` 헤더에 적힌 시간만큼 기다리세요.

응답 헤더

Retry-After
요청을 다시 시도하기 전에 기다릴 초.
RateLimit-Policy
적용 중인 한도. IETF 초안 draft-ietf-httpapi-ratelimit-headers 형식이며, 쉼표로 구분한 "<name>";q=<quota>;w=<window in seconds> 항목으로 이루어져요. key 항목은 API 키의 요청 속도예요(할당량은 버스트, 시간 창은 버스트가 완전히 다시 채워지는 시간이에요. 세션에서는 user, 자격 증명이 없으면 ip예요). minute, day, month 항목은 UTC 기준 달력상의 분, 일, 월에 대한 조직의 할당량이에요.
RateLimit
RateLimit-Policy 헤더의 각 한도에서 남은 양: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
RateLimit-Policy 헤더에서 가장 엄격한 항목(남은 요청 수가 가장 적은 항목)의 한도.
X-RateLimit-Remaining
가장 엄격한 한도에서 남은 요청 수.
X-RateLimit-Reset
가장 엄격한 한도가 초기화될 때까지 남은 초.

application/json

객체: Error

오류 코드

모든 요청에 공통으로 쓰이는 코드 외에 이 엔드포인트가 error.code로 반환할 수 있는 코드예요.

안전한 재시도

POST와 PATCH 요청마다 Idempotency-Key 헤더(예: UUID)를 보내세요. 24시간 안에 같은 키로 재시도하면 요청을 다시 실행하지 않고 저장된 응답을 반환해요.

호출 한도

응답에는 RateLimit, RateLimit-Policy 헤더와 이전 헤더인 X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset이 담겨요. 429 응답에는 초 단위의 Retry-After 헤더가 있어요. 그만큼 기다린 뒤 재시도하세요.

← webhooks · API 레퍼런스

curl -X PATCH 'https://api.sursa.com/v1/webhooks/1' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/webhooks/sursa","description":"Customer support articles","events":["card.*"]}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

사용해 보기

API 키

키는 이 탭의 메모리에만 보관되며 https://api.sursa.com 주소로만 전송돼요.

요청은 조직의 실제 데이터에 적용돼요.

Idempotency-Key header

webhook_id path *

Idempotency-Key

비워 두면 요청마다 새 키가 생성돼요.

요청 본문(JSON)