Webhooks
kokiwa sends a POST request to your https URL when a payment is credited or a payment intent changes status. Manage webhook URLs on the Webhooks page of the merchant dashboard.
Want working code to copy? Integration examples in Node.js, Python, PHP, Go and Java
Request format
{
"id": "evt_3Fk9Qw2Lm7Rt5Xb1Nc8Vz4",
"type": "payment_intent.paid",
"created_at": "2026-11-02T08:41:07Z",
"livemode": true,
"data": {
"payment_intent": { "id": "pi_7Gm4Rk2Wp9Ls1Qv8Bd3Zt6", "object": "payment_intent", "status": "paid", "...": "..." },
"deposit": { "id": "dep_9Kx2Pa6Wn3Ty8Lq5Rb1Ms4", "object": "deposit", "status": "settled", "...": "..." }
}
}| Header | Description |
|---|---|
Kokiwa-Signature | Signature in the form t=timestamp,v1=signature. |
Kokiwa-Event-Id | Event ID, the same as id in the body. |
Kokiwa-Delivery-Attempt | Delivery attempt, starting at 1. |
data.deposit is the deposit object. data.payment_intent is the object returned when you retrieve a payment intent, without checkout_url and livemode; livemode is at the top of the event.
Event types
| type | When it is sent | data |
|---|---|---|
payment_intent.paid | A payment intent was paid in full | payment_intent、deposit |
payment_intent.partially_paid | A payment intent received part of its amount | payment_intent、deposit |
payment_intent.expired | A payment intent expired unpaid | payment_intent |
payment_intent.paid_late | Funds arrived after a payment intent expired | payment_intent、deposit |
deposit.confirmed | A deposit was confirmed on-chain, from a payment intent or a deposit address | deposit |
deposit.settled | A deposit reached your payout address | deposit |
webhook.test | A test event you sent from the dashboard | message |
A wallet payment settles in the payment transaction, so deposit.confirmed and deposit.settled arrive together. A transfer sends deposit.confirmed first and deposit.settled after sweeping. Credit the user on confirmed; there is no need to wait for settled.
Verify the signature
Each webhook URL has its own signing secret (whsec_…), shown once when created.
- Read
tandv1fromKokiwa-Signature. - Compute HMAC-SHA256 of the string
{t}.{raw body}with the secret, encode as lowercase hex, and compare withv1in constant time. - Reject requests where
tis more than 5 minutes from the current time.
Use the raw request body. Parsing the JSON and serializing it again changes the bytes, and the signature will not match.
Node.js
import crypto from "node:crypto";
import express from "express";
const app = express();
const secret = process.env.KOKIWA_WEBHOOK_SECRET;
app.post("/kokiwa/webhook", express.raw({ type: "application/json" }), (req, res) => {
const header = req.get("Kokiwa-Signature") ?? "";
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const expected = crypto.createHmac("sha256", secret)
.update(`${parts.t}.${req.body}`).digest("hex");
const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
const match = parts.v1?.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
if (!fresh || !match) {
return res.sendStatus(400);
}
const event = JSON.parse(req.body);
// deduplicate by event.id, process, then return 2xx quickly
res.sendStatus(200);
});Go
func verify(secret, body []byte, header string) bool {
var t, v1 string
for _, p := range strings.Split(header, ",") {
k, v, _ := strings.Cut(strings.TrimSpace(p), "=")
switch k {
case "t":
t = v
case "v1":
v1 = v
}
}
ts, err := strconv.ParseInt(t, 10, 64)
if err != nil || math.Abs(float64(time.Now().Unix()-ts)) > 300 {
return false
}
mac := hmac.New(sha256.New, secret)
mac.Write([]byte(t + "."))
mac.Write(body)
return hmac.Equal([]byte(hex.EncodeToString(mac.Sum(nil))), []byte(v1))
}Python
import hashlib, hmac, time
def verify(secret: bytes, body: bytes, header: str) -> bool:
parts = dict(p.strip().split("=", 1) for p in header.split(","))
t, v1 = parts.get("t", ""), parts.get("v1", "")
if not t.isdigit() or abs(time.time() - int(t)) > 300:
return False
expected = hmac.new(secret, f"{t}.".encode() + body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, v1)Responses and retries
- Return any 2xx within 10 seconds and move slow work to a background queue.
- Non-2xx responses, timeouts and connection failures are retried 11 times, after 30 seconds, 2, 10 and 30 minutes, then 1, 2, 4, 8, 12, 24 and 20 hours. Delivery stops after about 3 days.
- An event can arrive more than once and events are not ordered. Deduplicate by event
id, and callGET /v1/payment_intents/{id}for the latest status. - The Webhooks page shows the result of each delivery and lets you redeliver by hand.
- If every retry fails, use
GET /v1/depositsto catch up on missed deposits.
Telegram notifications
Link @KoKiWaPayBot on the Settings page to get a message for every deposit. It is only a reminder and does not replace webhooks.