Webhooks overview

Webhooks let your platform react to payment activity the moment it happens. As transactions, refunds, disputes, and subscriptions change state across your connected providers, Tokeflow POSTs a normalized JSON event to the HTTPS endpoint(s) you configure.

Instead of polling the API, you subscribe once and let events come to you. Because Tokeflow normalizes webhooks across every provider you orchestrate, you write one handler — not one per provider — and the event shape stays the same no matter which acquirer processed the charge.

Why webhooks

How delivery works

1. An event occurs. A transaction, refund, dispute, payment method, or subscription changes state.
2. Tokeflow builds a normalized event and signs it with your endpoint's signing secret.
3. Tokeflow POSTs the event to each matching endpoint as a JSON request body.
4. Your endpoint responds. A 2xx status (returned quickly) marks the delivery as succeeded. Anything else triggers a retry.

Configure your endpoints

You register webhook endpoints in the Tokeflow Dashboard during onboarding (and any time afterward). For each endpoint you provide:

The event envelope

Every webhook request body shares the same top-level shape. The data.object field carries the resource the event is about (a transaction, refund, subscription, and so on).

{
  "id": "evt_8f3c2a1b9d7e4f60",
  "type": "transaction.authorized",
  "created_at": "2026-01-15T12:30:00.000Z",
  "data": {
    "object": {
      "id": "tx_3n8Q2k1p7w",
      "merchant_id": "mrc_7Yh2Kd9",
      "external_order_id": "order-2026-0042",
      "customer": {
        "id": "cust_5Tg8Lp2",
        "email": "buyer@example.com"
      },
      "previous_status": "pre_authorized",
      "current_status": "authorized",
      "amount_authorized": 15000,
      "amount_captured": 15000,
      "currency": "BRL",
      "changed_at": "2026-01-15T12:30:00.000Z"
    }
  }
}

What data.object contains

The shape of data.object depends on the event family. See Event types for the full catalog and per-resource fields.

Request headers

Each delivery is an HTTP POST with a JSON body and these notable headers:

Responding to events

Your endpoint should acknowledge receipt fast and do the real work afterward.

• Respond 2xx within a few seconds. Return the response as soon as you've safely persisted the event (for example, enqueued it). Tokeflow treats any 2xx as success.
• Process asynchronously. Do slow work — fulfillment, emails, downstream calls — outside the request/response cycle so you never risk a timeout.
• Deduplicate by id. Retries and at-least-once delivery mean the same event id can arrive more than once. Make handling idempotent: record processed event IDs and skip duplicates.
• Don't depend on ordering. Events may arrive out of order, especially after a retry. Use the resource's status fields (and changed_at) rather than assuming arrival order reflects the true sequence.

// Express example — acknowledge fast, process async.
// Use a raw body parser on this route so signature verification sees exact bytes.
import express from "express";

const app = express();

app.post(
  "/webhooks/tokeflow",
  express.raw({ type: "application/json" }),
  (req, res) => {
    // 1. Verify the signature against the raw body (see Verifying signatures).
    if (!verifyTokeflowSignature(req)) {
      return res.status(400).send("invalid signature");
    }

    const event = JSON.parse(req.body.toString("utf8"));

    // 2. Deduplicate and enqueue for async processing.
    enqueueForProcessing(event); // your job queue

    // 3. Acknowledge immediately.
    return res.status(200).send("ok");
  },
);

Delivery, failures, and retries

Tokeflow records every delivery attempt for every endpoint, so you can audit exactly what was sent and how your endpoint responded.

A delivery is considered successful only when your endpoint returns an HTTP 2xx. A delivery fails when it returns a non-2xx status, times out, or is unreachable. Each request has a delivery timeout of 30 seconds — keep handlers well under that.

When a delivery fails, Tokeflow retries with exponential backoff:

After the retry schedule is exhausted, the delivery is abandoned and no further attempts are made. The full delivery history — status codes, response snippets, attempt counts, and next retry time — is retained for inspection.

Security checklist

• Verify every signature. Reject requests whose X-Tokeflow-Signature doesn't validate against the raw body and your whsec_ secret.
• Enforce a timestamp tolerance. Reject events whose signature timestamp is outside a small window (for example, 5 minutes) to mitigate replay attacks.
• Use HTTPS only. Endpoints must be HTTPS so payloads and signatures are protected in transit.
• Keep secrets server-side. The webhook signing secret, like your sk_* API keys, must never appear in browser or client code.

Next steps

• Event types — the full catalog of event types and the resource carried in data.object.
• Verifying signatures — validate X-Tokeflow-Signature step by step.
• Authentication — how API keys, scopes, and environments work.