Webhooks

​

TL;DR

1. Configure uma URL HTTPS pública para receber eventos.
2. Responda 200 OK em milissegundos.
3. Deduplicate por event_id (id do webhook).
4. Processe assíncrono e reconcilie pelo recurso (data.id ou data.object.id).

​

Famílias de eventos

​

Handler de referência (Node/Bun)

app.post("/webhooks/pagou", async (req, reply) => {
  const event = req.body as { id: string };

  // 1) Acknowledge rápido
  reply.code(200).send({ received: true });

  // 2) Idempotência
  if (await alreadyProcessed(event.id)) {
    return;
  }

  // 3) Processamento assíncrono
  await enqueueWebhook(event);
});

​

Fluxo recomendado de reconciliação

1. Atualize estado local no webhook.
2. Em erro transitório, consulte recurso na API (GET /v2/transactions/{id} ou GET /v2/transfers/{id}).
3. Mantenha logs com: id do evento, tipo do evento e ID da entidade.