Webhook

Webhook을 이용, KOMOJU에서 생성된 이벤트 알림을 설정할 수 있습니다. 이벤트가 생성되면 이벤트 정보가 기재된 JSON 오브젝트 포함 POST 요청를 사용중인 어플리케이션에 전송합니다. Webhook을 이용하면 사용중의 어플리케이션이 결제 내용 저장/환불 등의 중요 이벤트 생성 시기를 즉시 알려주므로, 이런 이벤트들을 어플리케이션 내에서 처리할 수 있습니다.

Webhook 등록 페이지에서 새로운 Webhook을 등록할 수 있습니다. Webhook을 등록하기 전에 어플리케이션이 Webhook을 수신할 수 있도록 엔드포인트 URL을 설정해 주십시오. 엔드포인트 URL 설정이 완료되면 새로운 Webhook을 등록할 수 있습니다. Webhook 등록 후 바로 ping 이벤트를 전송하므로 이벤트 관리도 용이합니다.

이벤트

특정한 API 리소스상에서 작업이 생성되면 KOMOJU 내에서 이벤트가 생성됩니다. 어플리케이션에서 결제 완료나 환불 등의 결제 상태 변경과 같은 중요 이벤트 알림을 설정했는지 확인해 주십시오. Webhook 등록 시에 알림을 설정할 이벤트를 선택해야 합니다.

알림 설정 가능 이벤트

이벤트 상세 내용
ping ping 이벤트
customer.created 고객 작성
customer.updated 고객 갱신
customer.deleted 고객 삭제
payment.authorized 결제 가상 매상화
payment.captured 요금 결제 완료
payment.updated 결제 갱신 완료
payment.expired 결제 유효기한 만료
payment.cancelled 결제 취소
payment.refund.created 요금 환불 작성
payment.refunded 요금 환불
payment.failed 결제 처리 실패
payout.created 정기 결제 작성
subscription.created The subscription was created
subscription.captured The subscription payment was captured
subscription.failed The subscription payment failed
subscription.suspended The subscription was suspended
subscription.deleted The subscription was deleted
submerchant.approved The submerchant was approved
submerchant.suspended The submerchant was suspended
submerchant.disabled The submerchant was disabled
submerchant.updated The submerchant was updated

Webhook Delivery

Webhook Delivery는 생성된 이벤트 정보를 포함한 Webhook URL로의 POST 요청를 말합니다. 각 Webhook Delivery에는 메타데이터 헤더와 이벤트에 관한 JSON 오브젝트가 포함됩니다.

HTTP 헤더

명칭 상세 내용
X-Komoju-ID Webhook Delivery 고유 ID
X-Komoju-Signature 보안 토큰과 Webhook의 request body를 이용해 계산된 SHA-2 HMAC
X-Komoju-Event Webhook 이벤트 명칭 (예: payment.captured)
User-Agent Komoju-Webhook
Content-Type application/json

속성

명칭 상세 내용
type Webhook 이벤트 타입 (예: payment.captured)
object event
data API 리소스를 표시한 해시
created_at 이것은 다음과 같은 ISO 8601 포맷의 타임스템프입니다: YYYY-MM-DDTHH:MM:SSZ.

Webhook Delivery 샘플

POST http://example.com/hook HTTP/1.1

Host: example.com
X-Komoju-Id: 6cul2yma626autvvxz2xre1qr
X-Komoju-Signature: 75e653443e6543ee4c4b0665c73a4818216c9464f4a3ac959bff5ebafc105693
X-Komoju-Event: payment.authorized
User-Agent: Komoju-Webhook
Content-Type: application/json
Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
Accept: */*
{
  "id": "dv7ywuavew3n2meqsllj5bbob",
  "type": "payment.authorized",
  "resource": "event",
  "data": {
    "id": "8xz5cn01gkt37cz0myd98k2f1",
    "resource": "payment",
    "status": "authorized",
    "amount": 1000,
    "tax": 80,
    "customer": null,
    "payment_deadline": "2018-11-20T14:59:59Z",
    "payment_details": {
      "type": "bank_transfer",
      "email": "test@example.com",
      "order_id": "Y5236584956",
      "bank_name": "三井住友銀行",
      "account_branch_name": "ひなぎく",
      "account_number": "6",
      "account_type": "普通預金",
      "account_name": "株式会社DEGICA(カブシキガイシャ デジカ)",
      "instructions_url": "https://komoju.com/ja/instructions/8xz5cn01gkt37cz0myd98k2f1"
    },
    "payment_method_fee": 0,
    "total": 1080,
    "currency": "JPY",
    "description": null,
    "captured_at": null,
    "external_order_num": "123",
    "metadata": {
    },
    "created_at": "2018-11-13T06:19:49Z",
    "amount_refunded": 0,
    "locale": "ja",
    "refunds": [

    ],
    "refund_requests": [

    ]
  },
  "created_at": "2018-11-13T06:19:49Z"
}

ping 이벤트

Webhook이 작성되면 즉시 어플리케이션의 Webhook URL로 ping 이벤트를 전송합니다. 이 이벤트에는 작성된 Webhook 설정 정보가 포함됩니다. 테스트를 원할 때는 Webhook 페이지의 “재전송" 버튼을 클릭하여 Webhook Delivery를 재전송할 수 있습니다.

Webhook Delivery 샘플

POST http://example.com/hook HTTP/1.1

Host: example.com
X-Komoju-Id: 1lqjmj6k7li996cdiqxqqzf1k
X-Komoju-Signature: ee52defb62c1d48125741bfe92a13b6cbffc97b0b3a26b5cab582f766a4ae97e
X-Komoju-Event: ping
User-Agent: Komoju-Webhook
Content-Type: application/json
Accept-Encoding: gzip;q=1.0,deflate;q=0.6,identity;q=0.3
Accept: */*
{
  "id": "do33foclbroj52ib9whb6yh4m",
  "type": "ping",
  "resource": "event",
  "data": {
    "id": "bll40gxhuhcw19vor5kx55akw",
    "resource": "webhook",
    "url": "http://example.com/hook",
    "active": true,
    "event_list": [
      "ping",
      "payment.captured"
    ],
    "created_at": "2018-11-13T06:19:49Z"
  },
  "created_at": "2018-11-13T06:19:49Z"
}

시크릿 토큰

Webhook 요청이 KOMOJU로부터 전송된 것임을 검증하기 위해 SHA-2 HMAC 서명가 사용됩니다. 이 때 당신이 Webhook을 작성 또는 갱신 시에 설정하는 시크릿 토큰이 이용됩니다.

시크릿 토큰이 설정되면, 요청에는 HMAC customer header인 X-Komoju-Signature가 포함됩니다. 이 헤더는 시크릿 토큰을 키로 사용하는 request body의 계산된 HMAC를 말합니다. 시크릿 토큰을 사용하면 그 서명을 계산하여 KOMOJU에서 전송되는 서명과의 비교가 가능해집니다.

샘플 코드(Ruby)

주의: 서명을 확인할 때, ==와 같은 단순 문자열 비교는 타이밍 어택 피해에 노출되기 쉬우므로 권장하지 않습니다. 대신에 일정 시간 알고리즘(constant-time algorithm)을 권장합니다. 만약 ruby를 사용중이라면, secure_compare 이용이 효율적입니다.

require "sinatra"

WEBHOOK_SECRET_TOKEN = "keep it secret, keep it safe!"

post '/hook' do
  request_body = request.body.read
  signature = OpenSSL::HMAC.hexdigest('sha256', WEBHOOK_SECRET_TOKEN, request_body)
  return 400 unless Rack::Utils.secure_compare(signature, request.env["HTTP_X_KOMOJU_SIGNATURE"])

  "Hello World"
end

재전송

서버의 응답이 정상적인 상태 코드가 아니거나 KOMOJU가 서버와 정상적으로 접속할 수 없는 경우, Webhook Delivery 전송을 최대 25번까지 재시도합니다. 전송을 재시도할 때마다 재시도 시간의 간격은 점점 길어져 마지막에는 100시간 정도까지 벌어집니다. 마지막 재시도는 첫 번째 전송 이후 25일이 지나 발생하며 그 후에 Delivery는 실패 처리됩니다.

서버가 비오류 응답 코드를 반환했는데도 이벤트가 처리되지 않는 경우, 결제 정보 확인과 동시에 대시보드에서 언제든지 Webhook Delivery를 재전송 가능합니다.

IP 주소

Webhook 전송 서버의 IP 주소를 제공하지만, IP-based access control 사용은 권장하지 않습니다. 대신에 시크릿 토큰의 섹션에 기재된 방법을 선택하여 Webhook의 신뢰성을 확인해 주십시오.

또한 다음 IP 주소는 불가피한 사정에 의해 예고 없이 변경될 가능성이 있습니다.

  • 54.92.34.91
  • 54.250.139.124
  • 54.64.21.55
  • 54.250.170.194
  • 52.193.228.45
  • 52.192.41.65