Durable Functions 외부 이벤트 대기: AI 영상 웹훅

Azure Durable Functions에서 오케스트레이터는 wait_for_external_event(JavaScript에서는 waitForExternalEvent)로 외부 이벤트를 기다리고, 클라이언트 함수는 raise_event로 오케스트레이션의 인스턴스 ID에 그 이벤트를 발생시킵니다. 이 대기에는 기본적으로 기한이 없으므로 지속성 타이머와 경쟁시키세요. AI 영상 작업을 기다리려면 액티비티가 작업을 시작하고, 작업의 웹훅이 도착하면 HTTP 트리거 함수가 이벤트를 발생시킵니다.

Azure 관련 내용은 Microsoft Learn의 외부 이벤트, 지속성 타이머, 코드 제약 조건, 바인딩, Durable Functions HTTP API, HTTP 트리거 페이지와 Python 오케스트레이션 컨텍스트, 클라이언트 레퍼런스에서, Sume 관련 내용은 Format 호출하기 (영문), 실행과 결과 (영문), Run 웹훅 (영문)에서 가져왔습니다. 모두 2026-09-27에 확인했습니다. Sume에는 Azure 전용 커넥터가 없으며, 함수가 Sume의 HTTPS API를 직접 호출합니다.

각 구성 요소는 Sume 영상 실행과 어떻게 맞물리나요?

오케스트레이터 하나, 액티비티 두 개, HTTP 트리거 함수 하나로 이루어지며, 각각 맡은 일이 하나씩입니다. 오케스트레이터 코드는 결정적이어야 하므로 네트워크 호출은 액티비티에 둡니다.

오케스트레이터 코드는 어떤 모습인가요?

Python v2 프로그래밍 모델에서 오케스트레이터는 실행을 시작하고, 이벤트를 타이머와 경쟁시키며, 어느 쪽이 이기든 실행을 읽습니다. current_utc_datetime을 쓰면 재생할 때마다 기한이 같게 유지됩니다.

• start_sume_run(instance_id)는 Idempotency-Key를 인스턴스 ID로, communication.webhook_url을 웹훅 함수 URL 뒤에 ?instance=<instance_id>를 붙인 값으로 설정해 Format 실행을 POST하고, data.id를 반환합니다. 기본 URL과 SUME_API_KEY는 앱 설정에서 읽는데, 오케스트레이터는 앱 설정을 직접 읽어서는 안 됩니다.
• read_sume_run(run_id)는 /v1/format-runs/{run_id}를 GET하고, 영수증에서 status, primary_output_url, error를 반환합니다.

import azure.functions as func
import azure.durable_functions as df
from datetime import timedelta

myApp = df.DFApp(http_auth_level=func.AuthLevel.ANONYMOUS)

@myApp.orchestration_trigger(context_name="context")
def video_orchestrator(context: df.DurableOrchestrationContext):
    run_id = yield context.call_activity("start_sume_run", context.instance_id)
    deadline = context.current_utc_datetime + timedelta(minutes=100)
    timeout_task = context.create_timer(deadline)
    ended_task = context.wait_for_external_event("SumeRunEnded")
    winner = yield context.task_any([ended_task, timeout_task])
    if winner == ended_task:
        timeout_task.cancel()
    # Event or timeout (a canceled run never POSTs): read the receipt once.
    return (yield context.call_activity("read_sume_run", run_id))

웹훅 함수는 이벤트를 어떻게 발생시키나요?

Sume는 <timestamp>.<raw_body>에 HMAC-SHA256으로 서명하므로, 파싱하기 전에 req.get_body()의 원본 바이트를 확인하세요. 빈 시크릿은 거부하고, 시계 오차는 오 분까지 허용하며, sume-v1= 항목 중 하나라도 일치하면 수락하고, 비교에는 hmac.compare_digest를 쓰세요. 그런 다음 URL에 지정된 인스턴스에 이벤트를 발생시키세요.

• 인증 수준은 anonymous로 두고 서명에 의존하세요. Sume의 전달에는 Azure 키가 아니라 Sume 자체의 서명 헤더가 실리므로, 함수 키를 쓰려면 URL의 code 매개변수에 실어야 하고, 모든 영수증에 그 URL이 webhook_delivery.url로 표시됩니다.
• Durable Functions HTTP API의 기본 제공 raiseEvent URL을 Sume에 넘기지 마세요. 이 URL에는 모든 Durable Functions HTTP API에 접근할 수 있는 시스템 키가 담겨 있고, 그 경로에는 Sume의 서명을 확인하는 곳이 없습니다.
• raise_event는 404나 400 응답에서 예외를 발생시킵니다. 예외를 잡고 그래도 2xx로 응답하세요. 그 실행은 오케스트레이터의 타이머 경로가 처리합니다.

import hashlib, hmac, json, os, time

@myApp.route(route="sume-webhook", methods=[func.HttpMethod.POST])
@myApp.durable_client_input(client_name="client")
async def sume_webhook(req: func.HttpRequest, client: df.DurableOrchestrationClient):
    raw = req.get_body()  # the exact bytes Sume signed
    secret = os.environ.get("SUME_COM_WEBHOOK_SIGNING_SECRET", "").encode()
    ts = req.headers.get("x-sume-webhook-timestamp", "")
    if not secret or not ts.isdecimal() or abs(time.time() - int(ts)) > 300:
        return func.HttpResponse(status_code=401)
    expected = "sume-v1=" + hmac.new(secret, ts.encode() + b"." + raw, hashlib.sha256).hexdigest()
    entries = req.headers.get("x-sume-webhook-signature", "").split(",")
    if not any([hmac.compare_digest(e.strip(), expected) for e in entries]):
        return func.HttpResponse(status_code=401)
    event = json.loads(raw)
    try:
        await client.raise_event(req.params.get("instance"), "SumeRunEnded", {"run_id": event["run_id"]})
    except Exception:
        pass  # instance gone: its timer path reads the run
    return func.HttpResponse(status_code=204)

Durable Functions는 기다리는 동안 타임아웃되나요?

아니요, 타임아웃되지 않습니다. 외부 이벤트 대기 API는 무기한 기다리고, 기다리는 동안 함수 앱을 언로드할 수 있으며, Consumption 플랜에서는 오케스트레이터가 외부 이벤트를 기다리는 동안 요금이 발생하지 않습니다. 타임아웃되는 것은 개별 함수 실행입니다. 액티비티는 앱의 함수 타임아웃 안에 끝나야 하며, 기본값은 Flex Consumption 플랜에서 30분, 레거시 Consumption 플랜에서 5분입니다. Sume 실행을 시작하는 것은 HTTPS 호출 한 번이므로, 영상에 드는 몇 분은 함수가 실행되는 시간이 아니라 기다리는 시간입니다.

여러분이 정하는 타임아웃은 타이머의 타임아웃입니다. 100분 타이머는 Sume의 90분 기한보다 오래 가므로, read_sume_run이 확인할 때쯤이면 실행은 끝나 있습니다. POST를 보내지 않는 실행도 이 읽기로 알게 됩니다. 취소된 실행은 웹훅을 보내지 않고, 엔드포인트가 10회 시도를 모두 거부하면 아무것도 전달되지 않은 채 실행은 그대로 남습니다. 이벤트가 이기면 타이머를 취소하세요. Durable Functions는 타이머가 아직 남아 있는 동안에는 오케스트레이션을 Completed로 표시하지 않습니다.