Webhook events

The events Tocler Pay sends, their signature and the retries.

Updated 2 November 2026Live from Tocler

Event	When
payment.confirming	The transfer is seen on the chain.
payment.paid	All checks passed — read it back, then deliver.
payment.expired	The timer ended with nothing received.
payment.review	Something odd — Tocler will decide.
payment.refused	Refused after review.
payment.cancelled	Cancelled.
address.added	An own address was added.
address.disabled	An own address was switched off.

An event and its check

{
  "id": "evt_…",
  "object": "event",
  "type": "payment.paid",
  "created": 1793650000,
  "data": {
    "payment": {
      "id": "TCP-7KQ2M9XA",
      "status": "paid"
    }
  }
}

const crypto = require('crypto');
// header = req.headers['tocler-pay-signature'] → "t=<seconds>,v1=<hex>"
function verify(rawBody, header, secret) {
  const p = Object.fromEntries(String(header).split(',').map((x) => x.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(p.t)) > 300) throw new Error('too old');
  const expected = crypto.createHmac('sha256', secret).update(`${p.t}.${rawBody}`).digest('hex');
  const a = Buffer.from(expected);
  const b = Buffer.from(p.v1 || '');
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) throw new Error('bad signature');
  return JSON.parse(rawBody);
}

Headers: Tocler-Pay-Signature, Tocler-Pay-Event-Id, Tocler-Pay-Event-Type. Answer 2xx quickly; anything else is retried after 1 m, 5 m, 30 m, 2 h, 6 h, 12 h and 24 h. Handle the same event twice safely (by its id). A merchant can choose which events it gets (none chosen = all).

Was this page helpful?