Descripción general de los webhooks

Los webhooks permiten que tu plataforma reaccione a la actividad de pagos en el momento en que ocurre. A medida que las transacciones, reembolsos, disputas y suscripciones cambian de estado en los proveedores conectados, Tokeflow envía por POST un evento JSON normalizado al endpoint (o endpoints) HTTPS que configures.

En lugar de consultar la API mediante polling, te suscribes una sola vez y dejas que los eventos lleguen a ti. Como Tokeflow normaliza los webhooks de todos los proveedores que orquestas, escribes un único handler —no uno por proveedor— y la forma del evento se mantiene igual sin importar qué adquirente procesó el cargo.

Por qué usar webhooks

Cómo funciona la entrega

1. Ocurre un evento. Una transacción, reembolso, disputa, método de pago o suscripción cambia de estado.
2. Tokeflow construye un evento normalizado y lo firma con el secreto de firma de tu endpoint.
3. Tokeflow envía por POST el evento a cada endpoint coincidente como cuerpo de una solicitud JSON.
4. Tu endpoint responde. Un estado 2xx (devuelto rápidamente) marca la entrega como exitosa. Cualquier otra cosa desencadena un reintento.

Configura tus endpoints

Registras los endpoints de webhook en el Dashboard de Tokeflow durante el onboarding (y en cualquier momento posterior). Para cada endpoint proporcionas:

El envoltorio de eventos

El cuerpo de toda solicitud de webhook comparte la misma forma de nivel superior. El campo data.object lleva el recurso sobre el que trata el evento (una transacción, reembolso, suscripción, etc.).

{
  "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"
    }
  }
}

Qué contiene data.object

La forma de data.object depende de la familia del evento. Consulta Tipos de evento para ver el catálogo completo y los campos por recurso.

Encabezados de la solicitud

Cada entrega es un POST HTTP con un cuerpo JSON y estos encabezados destacados:

Responder a los eventos

Tu endpoint debe acusar recibo rápidamente y hacer el trabajo real después.

• Responde 2xx en pocos segundos. Devuelve la respuesta tan pronto como hayas persistido el evento de forma segura (por ejemplo, encolándolo). Tokeflow trata cualquier 2xx como éxito.
• Procesa de forma asíncrona. Realiza el trabajo lento —cumplimiento, correos, llamadas descendentes— fuera del ciclo de solicitud/respuesta para no arriesgar nunca un timeout.
• Deduplica por id. Los reintentos y la entrega al menos una vez implican que el mismo id de evento puede llegar más de una vez. Haz que el manejo sea idempotente: registra los IDs de eventos procesados y omite los duplicados.
• No dependas del orden. Los eventos pueden llegar desordenados, especialmente después de un reintento. Usa los campos de estado del recurso (y changed_at) en lugar de asumir que el orden de llegada refleja la secuencia real.

// 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");
  },
);

Entrega, fallos y reintentos

Tokeflow registra cada intento de entrega para cada endpoint, de modo que puedas auditar exactamente qué se envió y cómo respondió tu endpoint.

Una entrega se considera exitosa solo cuando tu endpoint devuelve un HTTP 2xx. Una entrega falla cuando devuelve un estado distinto de 2xx, agota el tiempo de espera o es inalcanzable. Cada solicitud tiene un timeout de entrega de 30 segundos: mantén los handlers muy por debajo de ese límite.

Cuando una entrega falla, Tokeflow reintenta con backoff exponencial:

Una vez agotado el calendario de reintentos, la entrega se abandona y no se realizan más intentos. Se conserva el historial completo de entrega —códigos de estado, fragmentos de respuesta, recuentos de intentos y próxima hora de reintento— para su inspección. En total, un endpoint que falla en todos los intentos se reintenta a lo largo de aproximadamente 26 horas antes de que la entrega se abandone. Cada registro de entrega se marca en el momento en que se resolvió —en caso de éxito o de abandono— y conserva el código de estado HTTP final y el fragmento de respuesta, de modo que el registro siempre refleja cuándo concluyó realmente la entrega, y no cuándo comenzó.

Lista de verificación de seguridad

• Verifica cada firma. Rechaza las solicitudes cuya X-Tokeflow-Signature no valide contra el cuerpo crudo y tu secreto whsec_.
• Aplica una tolerancia de marca de tiempo. Rechaza los eventos cuya marca de tiempo de la firma esté fuera de una ventana pequeña (por ejemplo, 5 minutos) para mitigar los ataques de repetición.
• Usa solo HTTPS. Los endpoints deben ser HTTPS para que las cargas útiles y las firmas estén protegidas en tránsito.
• Mantén los secretos del lado del servidor. El secreto de firma del webhook, al igual que tus claves de API sk_*, nunca debe aparecer en el navegador ni en el código del cliente.

Próximos pasos

• Tipos de evento — el catálogo completo de tipos de evento y el recurso que lleva data.object.
• Verificar firmas — valida X-Tokeflow-Signature paso a paso.
• Autenticación — cómo funcionan las claves de API, los scopes y los entornos.