i'mport Webhook

This guide describes how to use the i'mport Webhook to synchronize payment information on the i'mport server to the merchant server to compensate for data loss due to device or network instability.

What is a webhook?

A webhook is a mechanism for sending notifications to other services or applications when a specific event occurs. The webhook provider sends event information to the callback URL (endpoint) by creating an HTTP POST request when the event occurs. Webhooks are much more efficient in terms of resources and communication as they can only receive information relatd to desired events without polling data periodically. Using webhooks, you can extend functionality by integrating with custom functions or other applications.

Notifications via webhooks vs. callbacks

When the i'mport server sends a response to the client, the client may not receive the response after the payment process is complete for reasons, such as Wi-Fi disconnection or automatic browser reload. In this case, the i'mport server sends a webhook event to the server so that the payment information can be synchronized.
Webhook is a recommended setting. However, if you support virtual account payments, you must use a webhook to set up notifications for virtual account deposits.

i'mport Webhook is called when:
  • Payment is approved (all payment methods) (status : paid)
  • Virtual account is issued (status : ready)
  • Payment is deposited into virtual account (status : paid)
  • Scheduled payment is attempted (status : paid or failed)
  • Refund is processed via Admin Console (status : cancelled)
When a webhook event is called, the following POST request is generated for the notification URL endpoint.
  curl -H "Content-Type: application/json" -X POST -d '{ "imp_uid": "imp_1234567890", "merchant_uid": "order_id_8237352", "status": "paid" }' { NotificationURL }
The body of the webhook POST request contains the following information. The server can get the information and use it to query the payment information from the i'mport server and verify and store the payment information.
  • imp_uid: payment ID
  • merchant_uid: order ID
  • status: payment result

Set Callback URL

To set the webhook's notification URL to send the payment information to, log into the Admin Console and then go to System Settings > Webhook (Notification) tab and set the URL in the Common Webhook (Notification) URL field. To save the setting, click Save Webhook Setting at the bottom of the page.

Content-Type can be specified as application/json or application/x-www-form-urlencoded.

To test the callback URL, click the Test Webhook button to the right of the Notification URL field.

Testing webhook on localhost

In general, the webhook test is only available for domains that can be accessed from the external network. i'mport cannot access a callback URL that is on the localhost because localhost is only accessible from the local machine or shared network.

However, if you forward localhost to a domain accessible from an external network through the ngrok service, you can set the domain as the callback URL.

The following is an example of forwarding the development environment running on localhost:3000 to an externally accessible domain using ngrok. You can test the call by setting that domain as the callback URL.

Handle Webhook Event

For information about handling a webhook event after a payment, virtual account issuance or deposit, or refund, refer to the Configure notifications using webhook section in the General Payments guide.

For information about handling a webhook event after a scheduled (recurring) payment, refer to the Schedule payment section in the Subscription Payments guide.

Verify Webhook Request

An i'mport Webhook request is handled by the server-side endpoint. Since this endpoint is a public URL, you must verify that the request's client IP is an i'mport IP.

An i'mport Webhook request must be originated from one of the following two static IPs. A matching client IP identifies the source as i'mport, otherwise the request can be ignored.
  • 52.78.100.19
  • 52.78.48.223

Can new client IPs be added?

The IP of webhook requests is fixed to the aforementioned two IPs because i'mport uses a NAT gateway. Even if an i'mport server is added later, no additional IPs will be added.

Changes in Payment Processing Flow

i'mport provides conveninet payment integration by replacing the server's role of communicating with PG servers. Direct communication with the PG server had to be performed in the limited development environment supported by the PG, and involved complicated tasks, such as compiling and installing the PG module on the server. By using i'mport, you can easily and conveniently integrate payments through simple standard properties and REST APIs.

Using i'mport changes the flow of payment processing and the method of pushing payment data from i'mport server to the server. When payment occurs, payment data is first saved in the i'mport database, and then a webhook event or page redirection causes payment data to be saved in the server's database.
1Direct integration with PG module
The following is the payment processing flow for integrating with the PG module.
  1. Request payment to the server by entering the order and card information through the payment page.
  2. The server forwards the payment request to the PG server.
  3. The PG server requests approval from the credit card company with the payment information.
  4. The card company returns the approval result to the PG server.
  5. The PG server delivers the payment result to the server.
  6. The server stores the payment result in the database and outputs it on the payment page.
2Integration with i'mport
The following is the payment processing flow for integrating with i'mport.
  1. Request payment to the i'mport server by entering the order and card information through the payment page.
  2. The i'mport server forwards the payment request to the PG server.
  3. The PG server requests approval from the credit card company with the payment information.
  4. The card company returns the approval result to the PG server.
  5. The PG server sends the payment result to the i'mport server.
  6. The i'mport server stores the payment result in the i'mport database and sends the payment information to the server through a webhook.
  7. The i'mport server sends a 302 redirect response (Location: m_redirect_url) to the client.
  8. When callback is triggered by the 302 redirect response or redirected to m_redirect_url, payment information is transmitted to the server. The server stores payment information in the database.

i'mport does not guarantee the order of payment information delivery

In general, after i'mport server calls webhook, it does not guarantee the order in which the payment information arrives at the server. This is because i'mport sends a 302 redirect response to the client without waiting for a webhook response from the server. However, you can submit a special request to configure i'mport to wait for a webhook response before sending a 302 redirect response to the client so that the server always receives payment information from i'mport first.