Testing Omise WebHooks in test environment

This blog post is translated from OmiseのWebhookをテスト環境で試すためのアプリを用意しました by Akira Narita, Lead Developer at Omise.

What is Omise WebHooks?

WebHooks are simple HTTP POST requests that will be triggered from Omise servers whenever an action has been performed either through the API, or through the dashboard.

Whenever you create a charge on the test dashboard, you will be notified through Webhooks. Here’s an example.

{
  "object": "event",
  "id": "evnt_test_56vp5pfwjf1fqjn4ryy",
  "livemode": false,
  "location": "/events/evnt_test_56vp5pfwjf1fqjn4ryy",
  "key": "charge.create",
  "created": "2017-02-03T13:52:54Z",
  "data": {
    "object": "charge",
    "id": "chrg_test_56vp5pdrw28e2sgyr51",
    "livemode": false,
    "location": "/charges/chrg_test_56vp5pdrw28e2sgyr51",
    "amount": 100000,
    "currency": "jpy",
    "description": "Charge for order 3947",
    "status": "successful",
    "capture": true,
    "authorized": true,
    "reversed": false,
    "paid": true,
    "transaction": "trxn_test_56vp5pfhp4tv1o8xp85",
    "source_of_fund": "card",
    "refunded": 0,
    "refunds": {
      "object": "list",
      "from": "1970-01-01T00:00:00+00:00",
      "to": "2017-02-03T13:52:54+00:00",
      "offset": 0,
      "limit": 20,
      "total": 0,
      "order": null,
      "location": "/charges/chrg_test_56vp5pdrw28e2sgyr51/refunds",
      "data": [

      ]
    },
    "return_uri": "http://www.example.com/orders/3947/complete",
    "offsite": null,
    "reference": "paym_test_56vp5pe0wpv1c02a2vg",
    "authorize_uri": "https://api.omise.co/payments/paym_test_56vp5pe0wpv1c02a2vg/authorize",
    "failure_code": null,
    "failure_message": null,
    "card": {
      "object": "card",
      "id": "card_test_56vp5nkjti9mi10tmlx",
      "livemode": false,
      "country": "us",
      "city": "Bangkok",
      "postal_code": "10320",
      "financing": "",
      "bank": "",
      "last_digits": "4242",
      "brand": "Visa",
      "expiration_month": 2,
      "expiration_year": 2019,
      "fingerprint": "uqEgwbY6J9JcS3z/H1/eDzZmxXacMWo2gT09m+kj//0=",
      "name": "JOHN DOE",
      "security_code_check": true,
      "created": "2017-02-03T13:52:45Z"
    },
    "customer": null,
    "ip": null,
    "dispute": null,
    "created": "2017-02-03T13:52:53Z"
  }
}

You can add a WebHook endpoint from your dashboard.

How to add webhooks on the dashboard

Follow these steps

  1. Select the Webhooks menu from the left hand side of your Omise dashboard, and click on Edit.
  2. Update your preferred endpoint (receiver URL) and click Update.

When the event object occurs, a POST request will be sent to your endpoint. Remember that the URL specified must be HTTPS and must use a valid SSL certificate. Please refer to our WebHooks documentation for more information.

What kind of event will be sent?

Here's the full list of possible events.

Charge Events

Event Name Trigger
charge.create Charge has been created
charge.update Charge has been updated
charge.capture Charge has been captured (only for manual capture)
charge.reverse Charge has been reversed (only for manual capture)
charge.complete Complete charge (only for 3D-Secure charge and Internet Banking)

Customer Events

Event Name Trigger
customer.create Customer has been created
customer.update Customer has been created
customer.destroy Customer has been destroyed
customer.update.card Card is implicitly updated through a customer

Card Events

Event Name Trigger
card.update Card has been update
card.destroy Card has been destroyed

Dispute Events

Event Name Trigger
dispute.create Dispute has been opened
dispute.update Dispute has been updated
dispute.close Dispute has been closed

Recipient Events

Event Name Trigger
recipient.create Recipient has been created
recipient.update Recipient has been updated
recipient.destroy Recipient has been destroyed
recipient.activate Recipient has been activated
recipient.deactivate Recipient has been deactivated
recipient.verify Recipient has been verified

Refund Events

Event Name Trigger
refund.create Refund has been created

Transfer Events

Event Name Trigger
transfer.create Transfer has been created
transfer.update Transfer has been updated
transfer.destroy Transfer has been destroyed
transfer.send Transfer has been marked as sent
transfer.pay Transfer has been marked as paid
transfer.fail Transfer has been marked as failed

Getting started

For easy explanation, we created omise-webhook. The application is created using Sinatra, and we use ngrok to create the HTTPS URL for the endpoint. This allows us to keep JSON’s data which is sent from Omise WebHook as log when you start the app from your local machine.
The application works in environments which has git clone, homebrew, homebrew-cask, ruby v2.3.1. Please make sure you have applied the settings below before starting.

git clone git@github.com:akinrt/omise-webhook.git
cd omise-webhook

# bundlerをインストール
gem install bundler

# 必要なgemのインストール
bundle install --path vendor/bundle

# ngrokのインストール
brew cask install ngrok

# .envをつくる
touch .env

Your Omise secret key is required for .env, you can find it in your dashboard.

# .env
OMISE_TEST_SECRET_KEY=skey_test_xxxREPLACE_THIS_KEY_WITH_YOURS

Start application and ngrok, then confirm the HTTPS URL used for endpoint.

# Start application
bundle exec ruby app.rb

# Start ngrok in a new window
ngrok http 3000

Please use the HTTPS URL created from ngrok as endpoint.

ngrok link sample

This application will receive Omise webhook at /omise/webhook. You can copy the URL from ngrok and add it to your Omise dashboard.

Adding a webhooks URL

Whenever you create a charge or any other events, this application will save JSON object to omise-webhook/log/api/event/, where you can confirm the response.

As always, we’re more than happy to assist you. For questions or feedback, please send an email to support@omise.co