kokiwa

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.

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", "...": "..." }
  }
}
HeaderDescription
Kokiwa-SignatureSignature in the form t=timestamp,v1=signature.
Kokiwa-Event-IdEvent ID, the same as id in the body.
Kokiwa-Delivery-AttemptDelivery 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

typeWhen it is sentdata
payment_intent.paidA payment intent was paid in fullpayment_intent、deposit
payment_intent.partially_paidA payment intent received part of its amountpayment_intent、deposit
payment_intent.expiredA payment intent expired unpaidpayment_intent
payment_intent.paid_lateFunds arrived after a payment intent expiredpayment_intent、deposit
deposit.confirmedA deposit was confirmed on-chain, from a payment intent or a deposit addressdeposit
deposit.settledA deposit reached your payout addressdeposit
webhook.testA test event you sent from the dashboardmessage

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.

  1. Read t and v1 from Kokiwa-Signature.
  2. Compute HMAC-SHA256 of the string {t}.{raw body} with the secret, encode as lowercase hex, and compare with v1 in constant time.
  3. Reject requests where t is 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 call GET /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/deposits to 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.