elepayWebhook
Overview
To integrate with your system, elepay provides Webhooks and related tools for handling asynchronous notifications.
Webhook
A webhook is a mechanism for receiving notifications about events that occur in a service via an external URL over HTTP.
Tools
We provide development tools such as sending webhook notifications, request logs, and response format validation. See the developer tools for details.
Usage Guide
Use cases
With webhooks, you can have elepay notify any URL when events like the following occur:
- When a payment is completed successfully
- When a refund is completed successfully
Simply add a destination URL in the elepay dashboard and the above events will be delivered automatically.
Setup
Log in to the elepay dashboard. From the management screen shown below, add your webhook destination. Enter the URL, select event types, and click Add. You can register multiple webhook endpoints.
1. Webhook URL
Specify the URL that receives webhook notifications under “Developer Settings / Webhook”.
2. Test mode and Live mode
Both Test mode and Live mode are supported. Use the Test/Live toggle at the top of the dashboard to manage settings for each environment.
3. Webhook events
elepay defines the webhook notification events. When an event listed below occurs, a corresponding webhook notification is sent.
Request
All elepay webhooks are sent as POST requests. The request body contains the event JSON data.
Event list
These are the event types actually sent by elepay. The event type is contained in the JSON under type.
| Type | Description |
|---|---|
charge.succeeded | Payment succeeded |
charge.revoked | Payment revoked |
refund.succeeded | Refund succeeded |
source.activated | Authorization succeeded |
source.inactivated | Authorization invalidated |
reader.activated | Reader pairing completed |
Below is an example of the event data sent when a payment of 1800 JPY succeeds.
{
"id": "evt_la06CoQAiPojSgJKe5gt3nwq",
"object": "event",
"createTime": 1543944030817,
"liveMode": false,
"type": "charge.succeeded",
"data": {
"object": {
// Charge object
}
}
}The data field contains the detailed content of the event. Its structure matches the JSON returned by the API.
Receiving notifications
Success handling
When you successfully receive a webhook notification, return an HTTP 2xx status code.
Error handling
If receiving the webhook fails, be sure to return an HTTP 4xx or 5xx status code. elepay will automatically retry. Retries occur first 3 times at 1‑minute intervals, then 2 more times at 10‑minute intervals.
If delivery still fails, use the synchronous APIs to reconcile the payment status.
| Retry | Count | Interval |
|---|---|---|
| 1–3 times | Total 3 | 1 time / 1 min |
| 4–5 times | Total 2 | 1 time / 10 min |
Authenticity
All webhook requests from the elepay servers include an elepay-signature header.
The header looks like this:
Format:
elepay-signature: t=[timestamp],sign=[signature]
Example:
elepay-signature: t=1581064080,sign=100dcc3d839c89cd91ecdd23d7305b2fdb8ae73b498c27efd812b25fc86ec702📘 Depending on your framework, HTTP headers may not preserve the all‑lowercase
elepay-signature. In that case, tryElepay-Signature.
Authenticity verification logic
The signature is generated by applying the HMAC‑SHA256 algorithm using the timestamp and a verification secret. You can view or regenerate the secret on the webhook details page in the dashboard.
- Extract the timestamp and signature from the header.
- Read the request body data.
- Create the string:
<timestamp from 1> + "." + <body from 2>. - Using the verification secret, sign the string from step 3 with HMAC‑SHA256.
- Compare the result from step 4 with the signature from step 1 to verify authenticity.
Last updated on