Webhooks

{  "id": "evt_6Ff7Gg8Hh9Ii0J",  "object": "event",  "type": "charge.paid",  "api_version": "2026-11-01",  "created_at": "2026-11-03T14:23:41.000Z",  "data": {    "object": {      "id": "chg_4Fp9KzW1xQm7Rt",      "object": "charge",      "amount": 49700,      "currency": "BRL",      "status": "paid",      "method": "pix",      "card": null,      "description": "Curso Identidade Visual do Zero",      "customer_id": "cus_8Hq2LmZr4TxN1a",      "product_id": "prod_3Vb7QpK9sWd2Ee",      "price_id": "price_5Kd1NcR8vYq3Hm",      "link_id": "plink_2Wn6HsT9cVb4Lq",      "subscription_id": null,      "fee": null,      "net": null,      "refunded_amount": 0,      "failure_code": null,      "created_at": "2026-11-03T14:22:05.000Z",      "paid_at": "2026-11-03T14:23:41.000Z",      "expires_at": "2026-11-03T14:37:05.000Z",      "available_at": null,      "checkout_url": "https://krokopay.app/pay/chg_4Fp9KzW1xQm7Rt"    }  }}

{  "id": "evt_4Zz5Aa6Bb7Cc8D",  "object": "event",  "type": "charge.refunded",  "api_version": "2026-11-01",  "created_at": "2026-11-05T09:10:00.000Z",  "data": {    "object": {      "id": "chg_4Fp9KzW1xQm7Rt",      "object": "charge",      "amount": 49700,      "currency": "BRL",      "status": "partially_refunded",      "method": "pix",      "card": null,      "description": "Curso Identidade Visual do Zero",      "customer_id": "cus_8Hq2LmZr4TxN1a",      "product_id": "prod_3Vb7QpK9sWd2Ee",      "price_id": "price_5Kd1NcR8vYq3Hm",      "link_id": "plink_2Wn6HsT9cVb4Lq",      "subscription_id": null,      "fee": null,      "net": null,      "refunded_amount": 9900,      "failure_code": null,      "created_at": "2026-11-03T14:22:05.000Z",      "paid_at": "2026-11-03T14:23:41.000Z",      "expires_at": "2026-11-03T14:37:05.000Z",      "available_at": null,      "checkout_url": "https://krokopay.app/pay/chg_4Fp9KzW1xQm7Rt"    }  }}

POST /webhooks/krokopay HTTP/1.1Host: example.comContent-Type: application/jsonKrokoPay-Signature: t=1793715821,v1=9f2c4e1a7b3d5f8e0a6c2b4d9e1f3a5c7b9d0e2f4a6c8b1d3e5f7a9c0b2d4e6f​{ "id": "evt_6Ff7Gg8Hh9Ii0J", "object": "event", "type": "charge.paid", ... }

import { createHmac, timingSafeEqual } from "node:crypto";​// The endpoint's signing secret (whsec_test_…), kept in your environment.const WEBHOOK_SECRET = process.env.KROKOPAY_WEBHOOK_SECRET ?? "";// How old a signature may be. The proposal does not fix this value yet:// choose one for your integration and revisit it when it is defined.const TOLERANCE_SECONDS = 300;​/** Parses "t=<unix seconds>,v1=<hex>" into its parts. */function parseSignatureHeader(header: string): { timestamp: number; signatures: string[] } {  let timestamp = Number.NaN;  const signatures: string[] = [];  for (const part of header.split(",")) {    const [key, value] = part.trim().split("=", 2);    if (key === "t") timestamp = Number(value);    if (key === "v1" && value) signatures.push(value);  }  return { timestamp, signatures };}​export function verifySignature(rawBody: string, header: string | null, secret: string): boolean {  if (!header || !secret) return false;  const { timestamp, signatures } = parseSignatureHeader(header);  if (!Number.isFinite(timestamp) || signatures.length === 0) return false;  if (Math.abs(Date.now() / 1000 - timestamp) > TOLERANCE_SECONDS) return false;​  const expected = createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest();  return signatures.some((signature) => {    const received = Buffer.from(signature, "hex");    return received.length === expected.length && timingSafeEqual(received, expected);  });}​// Your own persistence and job queue.declare function alreadyProcessed(eventId: string): Promise<boolean>;declare function enqueue(event: KrokoPayEvent): Promise<void>;​interface KrokoPayEvent {  id: string;  type: string;  created_at: string;  data: { object: { id: string; object: string } };}​// A fetch-style handler: Request in, Response out.export async function POST(request: Request): Promise<Response> {  // Verify the raw body exactly as received, before parsing it.  const rawBody = await request.text();  const header = request.headers.get("KrokoPay-Signature");  if (!verifySignature(rawBody, header, WEBHOOK_SECRET)) {    return new Response("Invalid signature", { status: 400 });  }​  const event = JSON.parse(rawBody) as KrokoPayEvent;  // Deliveries can repeat: acknowledge duplicates without redoing the work.  if (await alreadyProcessed(event.id)) return new Response(null, { status: 200 });​  // Hand off slow work (emails, fulfilment) and answer right away.  await enqueue(event);  return new Response(null, { status: 200 });}

// Runs in your worker, after the webhook was acknowledged.// Re-read the object from the API when you need its latest state.async function handle(event: KrokoPayEvent): Promise<void> {  switch (event.type) {    case "charge.paid":      await markOrderPaid(event.data.object.id);      break;    case "charge.failed":    case "charge.expired":      await releaseReservedStock(event.data.object.id);      break;    case "charge.refunded":      await recordRefund(event.data.object.id);      break;    case "subscription.past_due":      await notifyBillingProblem(event.data.object.id);      break;    default:      // Ignore types you did not subscribe to or do not handle yet.      break;  }}

secret="whsec_test_2e4c6a8b0d1f3a5c7e9b"payload='{"id":"evt_test_local","object":"event","type":"charge.paid","api_version":"2026-11-01","created_at":"2026-11-03T14:23:41.000Z","data":{"object":{"id":"chg_test_local","object":"charge"}}}'t=$(date +%s)sig=$(printf '%s.%s' "$t" "$payload" | openssl dgst -sha256 -hmac "$secret" -hex | sed 's/^.* //')​curl -X POST http://localhost:3000/webhooks/krokopay \  -H "Content-Type: application/json" \  -H "KrokoPay-Signature: t=$t,v1=$sig" \  -d "$payload"