Pipedream에서 Sume 영상 실행의 웹훅 콜백 기다리기

Pipedream 워크플로가 Sume의 웹훅 콜백을 기다리게 하려면, 실행을 시작하는 코드 단계에서 $.flow.suspend()를 호출하고 반환된 resume_url을 communication.webhook_url로 넘기세요. Pipedream은 그 단계가 끝나는 시점에 일시 중지했다가, Sume가 실행 결과를 POST하면 워크플로 실행을 재개합니다. Sume는 실행이 완료되거나 실패할 때 이 POST를 한 번 보냅니다.

Sume에는 Pipedream 앱이 없으므로, Node.js 코드 단계에서 HTTPS로 API를 직접 호출합니다. Sume 관련 사실은 Format 호출하기 (영문), 실행과 결과 (영문), Run 웹훅 (영문)에서, Pipedream 동작은 2026-09-27에 확인한 Pipedream 문서에서 가져왔습니다. 웹훅 계약은 Sume Format 실행 수명주기에서 다룹니다.

$.flow.suspend는 Sume 실행과 어떻게 맞물리나요?

아래 Pipedream 규칙은 각각 실행에 직접적인 결과를 낳습니다.

실행을 시작하는 단계는 어떤 모습인가요?

API 키는 기본적으로 secret으로 설정되는 Pipedream 환경 변수에 두고 process.env로 읽으세요. Pipedream은 워크플로 코드에 키를 넣지 말라고 권합니다. Idempotency-Key는 이벤트에서 유도하고, 실행 ID는 이후 단계를 위해 반환하세요. 현재 코드에서는 키를 확인할 때 비교하는 본문에 웹훅 URL도 포함되고 resume_url은 워크플로 실행 하나에 속하므로, 새 워크플로 실행에서 같은 키를 보내면 409 idempotency_conflict가 돌아오고 두 번째 실행은 시작되지 않습니다.

import axios from "axios";

export default defineComponent({
  async run({ steps, $ }) {
    const order = steps.trigger.event;
    const { resume_url } = $.flow.suspend(2 * 60 * 60 * 1000); // 2 hours
    const { data } = await axios({
      method: "POST",
      url: "https://api.sume.com/v1/formats/sume/sume-product-commercial/runs",
      headers: {
        Authorization: `Bearer ${process.env.SUME_API_KEY}`,
        "Content-Type": "application/json",
        "Idempotency-Key": `order-${order.id}-v1`,
      },
      data: {
        instruction: "Make a vertical product commercial from the attached photo.",
        attachments: [{ type: "input_image", image_url: order.photo_url }],
        generation_spend_cap_usd: 20,
        communication: { webhook_url: resume_url },
      },
    });
    return { run_id: data.data.id };
  },
});

suspend 타임아웃은 얼마로 잡아야 하나요?

실행이 이어질 수 있는 시간보다 길게 잡으세요. Sume는 created_at으로부터 90분이 지난 실행을 failed로 강제 종료하고, 롱폼 호스트 영상은 보통 15~30분이면 끝나므로 위 코드의 두 시간이면 여유가 있습니다. 기본값인 24시간도 되지만, 끝내 콜백이 오지 않을 실행에도 워크플로 실행을 그만큼 열어 둡니다. Sume는 취소되거나 건너뛴 실행에는 아무것도 보내지 않습니다.

타임아웃이 지나면 Pipedream이 워크플로를 취소하고 suspend 이후 단계는 실행되지 않으므로, 실행 ID를 확인할 수 있는 곳에 보관하세요. 여러분의 타임아웃은 Sume 실행을 취소하지 않습니다. 실행은 계속 진행되며 계속 과금됩니다.

다음 단계는 콜백을 받아 무엇을 해야 하나요?

콜백은 결과를 확인하러 가라는 신호로 보고, 첫 단계가 반환한 실행 ID로 여러분의 키를 써서 실행을 읽으세요. GET /v1/format-runs/{run_id}는 Sume가 POST한 것과 같은 영수증을 data에 담아 반환합니다. 이 읽기는 여러분 자신의 키로 인증되므로, 워크플로가 $resume_data에 대한 Sume 서명을 확인할 필요가 없습니다.

• completed: 내구성 있는 media.sume.com URL인 primary_output_url을 게시합니다.
• failed: error를 읽고, 실행이 만든 결과물은 artifacts[]에서 확인합니다.
• resume_url로 가는 요청에는 Pipedream으로 가는 다른 HTTP 요청과 같은 한도가 적용되며, 본문 한도를 넘으면 Pipedream이 413으로 응답합니다. Sume는 1 MiB까지의 영수증을 본문에 그대로 담으므로, 실행이 큰 영수증을 돌려준다면 그 한도를 확인하세요.

대신 $.flow.rerun으로 폴링해야 할 때는 언제인가요?

콜백에 기대고 싶지 않을 때입니다. $.flow.rerun(delay, context, maxRetries)는 delay밀리초 뒤에 단계를 다시 실행하며, 최대 maxRetries번까지 반복하고 그 기본값은 10입니다. Pipedream 문서는 이 함수로 외부 작업이 완료될 때까지 폴링하는 예를 보여 줍니다. 10분 지연으로 10번 재시도하면 100분에 걸치므로 Sume의 90분 상한을 넘습니다. 마지막 재시도가 끝나면 워크플로는 다음 단계로 넘어가며, 그 단계에서 실행을 한 번 더 읽어야 합니다. Pipedream은 rerun이나 suspend로 워크플로가 일시 중지된 시간에는 요금을 매기지 않습니다.