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 |
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
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 on KOMOJU.
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