Webhooks

Webhooks allow you to subscribe to events in Komoju. When an event is triggered we will send your application a POST request containing a JSON object describing information about the event. Using webhooks your application can listen for important events like when a payment is captured, refunded, etc. and allow you to handle those events inside your application.

Creating a new webhook can be done from the webhooks creation page. Before creating a webhook you will need to setup an endpoint URL for your application to receive webhooks. Once you setup your endpoint URL you can create a new webhook. After creating the webhook we will immediately send you a ping event so you can test handling events.

Events

Events in Komoju are triggered when an action occurs on a particular API resource. You should make sure your application subscribes to important events like when the status of a payment changes e.g. captured, refunded, etc. Note, that when you create a webhook you will need to select which events you want to subscribe to.

Available events

Event Description
ping The ping event
customer.created The customer was created
customer.updated The customer was updated
customer.deleted The customer was deleted
payment.authorized The payment was authorized
payment.captured The payment was captured
payment.updated The payment was updated
payment.expired The payment has expired
payment.cancelled The payment was cancelled
payment.refund.created The refund was created
payment.refunded The payment was refunded
payment.failed The payment failed
payout.created The payout was 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

Webhook Delivery

A webhook delivery is simply a POST request to your applications webhook URL containing information about the event. Each webhook delivery contains some metadata headers and a JSON object describing the event.

HTTP Headers

Name Description
X-Komoju-ID Unique ID of the webhook delivery
X-Komoju-Signature Computed SHA-2 HMAC using your security token and the request body of the webhook
X-Komoju-Event Webhook event name e.g. payment.captured
User-Agent Komoju-Webhook
Content-Type application/json

Attributes

Name Description
type The type of webhook event e.g. payment.captured
object value of event
data A hash describing the API resource
created_at This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.

Example 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"
}

The Ping Event

When you create a webhook we immediately send you a ping event to your applications webhook URL. The event includes the webhook configuration which lists which events the webhook is listening to. For testing purposes you can re-deliver this webhook delivery from the webhooks pages by clicking the “Redeliver” button.

Example 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"
}

Secret Token

In order to ensure a webhook request came from Komoju we compute a SHA-2 HMAC signature using the secret token you provide when creating or updating a webhook.

When the secret token is set requests will contain the customer header X-Komoju-Signature which is the computed HMAC of the request body using the secret token as the key. Using the secret token you are able to compute a signature and compare it with the one we send you.

Code Example (Ruby)

Note: You should avoid using simple string comparisons such as == when checking the signature. These are prone to timing attacks and not advised. We recommend using a constant-time algorithm. If you're using ruby secure_compare does the trick.

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

Redelivery

In the event your server doesn’t respond with a successfull status code or Komoju is unable to establish a connection with your server, we will keep retrying the webhook 25 times before giving up. Each interval between attempts gets longer with the last interval lasting 100 hours. You will receive the last retry attempt 25 days later before the delivery is marked as failed.

In the case your server returned a non-error response code but did not process the event you can always re-deliver a webhook from the dashboard by viewing a payment.

IP Addresses

Although we do provide IP addresses for our webhook servers we strongly recommend against IP-based access control. We encourage merchants to instead check use the method outlined in the Secret Token section to ensure a webhooks authenticity.

Please note that the following IP addresses may change without notice due to unavoidable circumstances.

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