Webhooks

Um webhook é uma URL do seu servidor que a CartaFlow chama quando algo acontece na sua conta. A cada mudança de status de uma correspondência ou de uma verificação, enviamos um POST com o evento no corpo. Assim o seu sistema fica sabendo que uma correspondência foi postada, ou que um endereço foi verificado, sem consultar a API de tempos em tempos.

ConfigurarCopiar link da seção

O que chega no seu servidorCopiar link da seção

O corpo é um objeto event. Em data vem o objeto inteiro, como estava logo depois do acontecimento, então você não precisa consultar a API depois:

{
  "id": "evt_6Tq1Yz8Wm3Rb",
  "object": "event",
  "type": "letter.posted",
  "data": {
    "id": "ltr_8Kq2wX4mN7pR",
    "object": "letter",
    "status": "posted",
    "to": {
      "name": "Destinatário Exemplo",
      "street": "Rua Exemplo",
      "number": "128",
      "complement": "Ap. 52",
      "neighborhood": "Centro",
      "city": "São Paulo",
      "state": "SP",
      "postal_code": "01001-000"
    },
    "reference": "fatura-2026-10-0042",
    "metadata": { "customer_id": "1842" },
    "status_transitions": {
      "received_at": "2026-10-13T14:20:00Z",
      "in_production_at": "2026-10-13T21:00:00Z",
      "printed_at": "2026-10-14T10:42:00Z",
      "posted_at": "2026-10-14T16:05:00Z",
      "canceled_at": null,
      "failed_at": null
    },
    "created_at": "2026-10-13T14:20:00Z"
  },
  "created_at": "2026-10-14T16:05:00Z"
}

Para caber na página, o exemplo mostra só alguns campos de data. Na entrega real, data traz a correspondência completa, igual à resposta de GET /v1/letters/{letter_id}.

Cada entrega vem com três cabeçalhos:

Conferir a assinaturaCopiar link da seção

Confira a assinatura antes de confiar no conteúdo. Ela prova que a entrega veio da CartaFlow e que o corpo não foi alterado. A CartaFlow segue a especificação Standard Webhooks, que tem bibliotecas oficiais para várias linguagens.

Use o corpo cru, exatamente como chegou. Se o seu framework converter o JSON e você gerar o texto de novo, a assinatura não confere.

// npm install standardwebhooks express
import express from 'express';
import { Webhook } from 'standardwebhooks';

const app = express();
const webhook = new Webhook(process.env.CARTAFLOW_WEBHOOK_SECRET);

// express.raw mantém o corpo exatamente como chegou.
app.post('/webhooks/cartaflow', express.raw({ type: 'application/json' }), (req, res) => {
  let event;
  try {
    event = webhook.verify(req.body, req.headers);
  } catch {
    return res.status(400).send('Assinatura inválida');
  }

  res.status(200).end(); // responda primeiro
  queue.add(event); // processe depois, fora da requisição
});

import crypto from 'node:crypto';

export function verifyCartaflowWebhook(rawBody, headers, secret) {
  const id = headers['webhook-id'];
  const timestamp = headers['webhook-timestamp'];
  const signatures = headers['webhook-signature'];
  if (!id || !timestamp || !signatures) return false;

  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 5 * 60) return false;

  const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
  const expected = crypto.createHmac('sha256', key).update(`${id}.${timestamp}.${rawBody}`).digest();

  return signatures.split(' ').some((entry) => {
    const [version, signature] = entry.split(',');
    if (version !== 'v1' || !signature) return false;
    const received = Buffer.from(signature, 'base64');
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
  });
}

Responda rápido e processe depoisCopiar link da seção

Responda com qualquer status 2xx em até 15 segundos. Esse é o sinal de que você recebeu o evento. Faça o trabalho demorado, como atualizar o cadastro ou mandar um e-mail, depois de responder, por exemplo em uma fila.

Qualquer outra resposta, ou nenhuma resposta a tempo, faz a CartaFlow tentar de novo:

Depois da última tentativa, o evento não é enviado de novo. Ele continua disponível em GET /v1/events por 30 dias.

Repetições e ordemCopiar link da seção

• O mesmo evento pode chegar mais de uma vez. Uma entrega pode ser repetida mesmo que o seu servidor tenha recebido, por exemplo se a resposta se perder no caminho. Guarde o webhook-id dos eventos processados e ignore os repetidos.
• Os eventos podem chegar fora de ordem. Um letter.printed pode chegar depois de um letter.posted. Não deduza o status pela ordem de chegada: use o status e o status_transitions do objeto em data, que são uma foto do momento do evento. Para ter certeza do estado atual, consulte o objeto pela API.

Recuperar eventos perdidosCopiar link da seção

Se o seu servidor ficou fora do ar, busque o que perdeu em GET /v1/events, filtrando por created_after. Para ver a história de uma correspondência, use object_id. Os eventos ficam guardados por 30 dias e são os mesmos que os webhooks entregam.

Evento de testeCopiar link da seção

No painel, em Desenvolvedores > Webhooks, o botão Enviar evento de teste envia para o seu endpoint uma entrega do tipo webhook.test. Use para conferir que a URL responde, que a assinatura confere e que o seu servidor responde 2xx a tempo.

• A entrega tem os mesmos cabeçalhos e a mesma assinatura das outras, com o segredo whsec_ do webhook.
• O corpo segue o formato de qualquer evento, com type: "webhook.test" e um objeto de exemplo em data. Esse objeto não existe na sua conta: não grave nada a partir dele.
• O evento de teste é enviado uma vez, sem novas tentativas, e nunca aparece em GET /v1/events.

Durante o desenvolvimento, a CartaFlow precisa alcançar a sua URL pela internet. Use um túnel, como ngrok ou Cloudflare Tunnel, para expor o seu servidor local com uma URL HTTPS, cadastre essa URL no painel e envie um evento de teste.

EventosCopiar link da seção

Cada mudança de status gera um evento com o nome objeto.novo_status. Quando uma correspondência é alterada no painel antes da produção, sem mudar de status (a data de envio ou o endereço, por exemplo), o evento é letter.updated, com a correspondência como ficou.