Webhooks

A webhook is a URL on your server that CartaFlow calls when something happens in your account. Every time a letter or a verification changes status, we send a POST with the event in the body. Your system learns that a letter was posted, or that an address was verified, without polling the API.

Set upCopy Anchor Link

What your server receivesCopy Anchor Link

The body is an event object. data carries the full object as it was right after the event, so you do not need to call the API afterwards:

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

To fit on the page, the example shows only some fields of data. In a real delivery, data holds the complete letter, the same as the response of GET /v1/letters/{letter_id}.

Each delivery comes with three headers:

Verify the signatureCopy Anchor Link

Verify the signature before trusting the content. It proves the delivery came from CartaFlow and that the body was not changed. CartaFlow follows the Standard Webhooks specification, which has official libraries for many languages.

Use the raw body, exactly as it arrived. If your framework parses the JSON and you serialize it again, the signature will not match.

// 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 keeps the body exactly as it arrived.
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('Invalid signature');
  }

  res.status(200).end(); // answer first
  queue.add(event); // process later, outside the request
});

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);
  });
}

Answer fast, process laterCopy Anchor Link

Answer with any 2xx status within 15 seconds. That tells us you received the event. Do slow work, such as updating records or sending an email, after answering, for example on a queue.

Any other answer, or no answer in time, makes CartaFlow try again:

After the last attempt, the event is not sent again. It stays available at GET /v1/events for 30 days.

Repeats and orderingCopy Anchor Link

• The same event can arrive more than once. A delivery can be repeated even if your server got it, for example when the response is lost on the way back. Store the webhook-id of the events you processed and skip repeats.
• Events can arrive out of order. A letter.printed may arrive after a letter.posted. Do not infer the status from arrival order: use status and status_transitions of the object in data, which are a snapshot from the moment of the event. To be sure of the current state, retrieve the object from the API.

Recover missed eventsCopy Anchor Link

If your server was down, fetch what you missed from GET /v1/events, filtering by created_after. To see the history of one letter, use object_id. Events are kept for 30 days and are the same ones webhooks deliver.

Test eventCopy Anchor Link

In the dashboard, under Desenvolvedores > Webhooks, the Enviar evento de teste (Send test event) button sends one delivery of type webhook.test to your endpoint. Use it to check that the URL answers, that the signature verifies and that your server answers 2xx in time.

• The delivery has the same headers and signature as any other, made with the webhook's whsec_ secret.
• The body has the shape of any event, with type: "webhook.test" and a sample object in data. That object does not exist in your account: do not store anything from it.
• The test event is sent once, with no retries, and never appears in GET /v1/events.

During development, CartaFlow has to reach your URL over the internet. Use a tunnel such as ngrok or Cloudflare Tunnel to expose your local server with an HTTPS URL, add that URL in the dashboard and send a test event.

EventsCopy Anchor Link

Every status change creates an event named object.new_status. When a letter is changed in the dashboard before production without changing status (its send date or address, for example), the event is letter.updated, with the letter as it is now.