웹훅

​

웹훅의 동작 방식

• 각 웹훅은 하나의 테이블과 하나 이상의 트리거 작업을 감시합니다.
• 일치하는 변경이 발생하면 Alforse는 전송을 큐에 넣고 비동기로 보내며, 보통 몇 초 이내에 전달됩니다.
• 각 전송은 해당 웹훅에 속한 비밀 값으로 서명되므로, 엔드포인트는 요청이 Alforse에서 왔음을 증명할 수 있습니다.
• 본문은 레코드가 변경되었다는 알림입니다. 조치를 취하기 전에 API 키로 현재 레코드를 가져오십시오.

​

구독 가능한 테이블

​

웹훅 설정

​

전송 내용

​

본문

{
  "type": "UPDATE",
  "table": "salesOrder",
  "companyId": "abc123",
  "record": { "id": "...", "salesOrderId": "SO000042", "status": "To Ship and Invoice" }
}

​

헤더

​

전송과 재시도

• 10초 이내에 성공 상태를 반환하지 않는 경우
• 5xx 또는 429를 반환하는 경우

• 그 외의 4xx 응답은 해당 변경의 전송을 종료합니다.
• Alforse는 리디렉션을 따라가지 않으므로 3xx 응답은 실패로 간주됩니다. 최종 URL을 설정하십시오.
• 거부된 주소로의 전송은 재시도하지 않습니다.

​

엔드포인트 설계

• 중복을 예상하십시오. 첫 번째 시도를 이미 처리한 뒤에 재시도가 도착할 수 있습니다. 하나의 레코드에 대한 별개의 변경은 type과 record.id가 같으므로, 이 조합이 아니라 x-omeriva-webhook-event로 중복을 제거하십시오.
• 장애 후에는 정합성을 맞추십시오. 폐기된 변경은 다시 전송되지 않습니다. 모든 이벤트를 처리해야 한다면 엔드포인트가 중단되었던 이후에 API를 조회하여 따라잡으십시오.

​

전송 검증

1. 파싱하기 전에 원본 본문을 확보합니다. JSON을 파싱했다가 다시 직렬화하면 바이트가 바뀌어 서명이 깨집니다.
2. HMAC을 계산하여 v1= 뒤의 값과 상수 시간 비교로 대조합니다.
3. 시계와 5분 넘게 차이 나는 타임스탬프는 거부하여 캡처된 요청의 재생을 막습니다. 모든 재시도는 새 타임스탬프로 다시 서명되므로 정상적인 재시도는 통과합니다.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyAlforseSignature(
  rawBody: string,
  signatureHeader: string,
  timestampHeader: string,
  secret: string,
  toleranceSeconds = 300
) {
  const timestamp = Number(timestampHeader);
  if (!Number.isFinite(timestamp)) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;

  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  const received = signatureHeader.replace(/^v1=/, "");
  return (
    received.length === expected.length &&
    timingSafeEqual(Buffer.from(received), Buffer.from(expected))
  );
}

​

문제 해결

​

관련 문서