AWS Lambda로 Sume 웹훅 받기: 함수 URL과 HMAC

AWS Lambda를 Sume 웹훅 수신기로 쓰려면 인증 유형이 NONE인 함수 URL을 만들고, 실행을 시작할 때 이 URL을 communication.webhook_url로 넘긴 뒤, 핸들러에서 Sume의 서명을 확인하세요. isBase64Encoded가 true이면 event["body"]를 base64에서 디코딩하고, <timestamp>.<raw_body>에 대한 HMAC-SHA256을 계산해, sume-v1= 항목 중 하나라도 일치하면 전달을 수락합니다. 그런 다음 Sume의 10초 시도 시간이 끝나기 한참 전에 204로 응답하세요.

AWS 관련 내용은 Lambda 개발자 안내서의 함수 URL 호출, 함수 URL 액세스 제어, 함수 타임아웃, 웹훅 자습서에서, Sume 관련 내용은 Run 웹훅 (영문), 웹훅 (영문), 실행과 결과 (영문)에서 가져왔습니다. 모두 2026-09-27에 확인했습니다. Sume에는 Lambda 전용 연동이나 패키지가 없으며, 아래 핸들러는 일반 Python 코드입니다. 서명, 재시도, 시크릿 교체 전반은 Sume 영상 실행용 서명된 웹훅에서 다룹니다.

Sume 웹훅에는 어떤 함수 URL 설정이 필요한가요?

전달이 제때 코드에 닿을지는 다섯 가지 설정이 좌우합니다. Sume는 localhost, 사설 네트워크, HTTPS가 아닌 웹훅 URL을 거부하는데, 함수 URL은 이 중 어디에도 해당하지 않습니다. 다른 거부 사유는 Sume 웹훅 URL 규칙에 정리되어 있습니다.

Lambda 이벤트에서 원본 본문은 어떻게 읽나요?

Lambda는 각 요청을 페이로드 형식 버전 2.0의 이벤트로 매핑합니다. headers에는 요청 헤더가 키-값 쌍으로 담기고, body는 문자열입니다. 요청의 콘텐츠 유형이 바이너리이면 body는 base64로 인코딩되며, 이 여부는 isBase64Encoded가 알려 줍니다. 먼저 디코딩하고, 그 바이트를 검증한 다음, JSON을 파싱하세요. 검증 로직은 Python 웹훅 HMAC 검증을 이벤트에 맞게 고친 것입니다. 헤더 이름을 소문자로 바꾸고, 빈 시크릿을 거부하며, 모든 sume-v1= 항목을 상수 시간으로 비교합니다. 코드를 짧게 유지하려고 시크릿을 환경 변수에서 읽지만, AWS는 API 키와 그 밖의 민감한 값에는 대신 Secrets Manager를 쓰라고 권장합니다.

Node.js 런타임에서는 @sume-com/sdk의 verifyWebhook이 같은 검증을 수행합니다. Node 18 이상이 필요하고, 디코딩한 바이트를 타입 배열로 받으며, event.headers를 일반 객체로 읽습니다.

import base64, hashlib, hmac, json, os, time

SECRET = os.environ["SUME_COM_WEBHOOK_SIGNING_SECRET"].encode()

def lambda_handler(event, context):
    body = event.get("body") or ""
    raw = base64.b64decode(body) if event.get("isBase64Encoded") else body.encode()
    headers = {k.lower(): v for k, v in (event.get("headers") or {}).items()}
    ts = headers.get("x-sume-webhook-timestamp", "")
    if not SECRET or not ts.isdecimal() or abs(time.time() - int(ts)) > 300:
        return {"statusCode": 401}  # no secret, or outside the 5-minute window
    digest = hmac.new(SECRET, f"{int(ts)}.".encode() + raw, hashlib.sha256).hexdigest()
    expected = f"sume-v1={digest}".encode()
    matched = False
    for entry in headers.get("x-sume-webhook-signature", "").split(","):
        matched = hmac.compare_digest(entry.strip().encode(), expected) or matched
    if not matched:
        return {"statusCode": 401}
    event_body = json.loads(raw)
    record_once(event_body)  # your queue or table, keyed on request_id or job_id
    return {"statusCode": 204}

AWS 웹훅 자습서와 무엇이 달라지나요?

AWS 자체 자습서는 인증 유형이 NONE인 함수 URL과 HMAC 검사로 웹훅 엔드포인트를 만듭니다. 하지만 그 검사는 Sume의 방식과 맞지 않으므로 다음 네 가지를 바꾸세요.

• 서명 대상. 자습서는 본문만으로 HMAC을 계산하고 x-webhook-signature 헤더 하나를 읽습니다. Sume는 <timestamp>.<raw_body>에 서명하고, x-sume-webhook-timestamp를 x-sume-webhook-signature와 함께 보냅니다.
• 해시할 바이트. 자습서는 도착한 그대로의 event['body']를 해시합니다. isBase64Encoded가 true이면 먼저 디코딩하세요.
• 비교 방식. 자습서의 Node.js 버전은 ===로 비교합니다. 자습서의 Python 버전이 hmac.compare_digest로 하듯 상수 시간으로 비교하세요. Python 문서는 이 함수가 타이밍 분석을 막도록 설계되었다고 설명합니다.
• 헤더 형식. 시크릿을 교체한 뒤 24시간 동안 Sume는 쉼표로 구분한 sume-v1= 항목 두 개를 최신순으로 보냅니다. 어느 항목이든 일치하면 수락하세요. 헤더 전체를 비교하는 검사는 그 기간의 모든 전달에서 실패합니다.

Lambda 함수 안에서 영상을 기다리면 왜 안 되나요?

실행이 호출보다 오래 걸릴 수 있기 때문입니다. Lambda 타임아웃은 최대 900초(15분)인 반면, 롱폼 호스트 영상은 보통 15~30분이면 끝나고, Sume는 created_at으로부터 최대 90분 뒤에 실행을 failed로 강제 종료합니다. 기다리다가 타임아웃된 함수는 실행을 멈추지 못합니다. 실행은 계속 진행되며 계속 과금됩니다.

그러니 어느 서비스에서든 함수 URL을 communication.webhook_url로 지정해 실행을 시작하고, data.id를 저장한 뒤 반환하세요. 생성 Job도 같은 URL을 webhook_url 또는 그 별칭인 callback_url로 받으며, 검증기 하나로 실행 전달과 Job 전달을 모두 처리할 수 있습니다.

서명이 확인되면 핸들러는 무엇을 해야 하나요?

다른 코드가 가져갈 수 있는 곳에 이벤트를 기록하고, 204로 응답한 뒤, 느린 작업은 핸들러 밖에서 하세요. 10초 시도 시간을 넘긴 응답은 Sume가 재시도합니다. 실행은 request_id로, Job은 job_id로 중복을 제거하고, result_url 읽기를 백업으로 유지하세요. 나머지 전달 규칙은 Sume 영상 실행용 서명된 웹훅에서 다룹니다.