Webhooks e relatórios

📨 O recibo (webhook)

Quando um aceite atinge um status final, o serviço entrega — via POST no webhook_url informado na criação — um recibo com a trilha completa de status. A entrega usa retry exponencial e é idempotente: se o recibo já foi entregue (ex.: reentrega de um evento de status pelo canal), a etapa de entrega é ignorada.

Formato do recibo — mesmo shape de um item de GET /api/v1/reports:

{
  "acceptance_id": "acc-9f8e7d6c-...",
  "execution_id": "exec-abc-123",
  "channel_type": "whatsapp",
  "current_status": "ACCEPTED",
  "metadata": {
    "organization": "Acme Ltda",
    "recipient_name": "João Silva"
  },
  "webhook_url": "https://meu-sistema.com/callbacks/acceptance",
  "expires_at": "2026-08-11T12:00:00Z",
  "trail": [
    { "status": "PENDING", "occurred_at": "2026-08-10T12:00:00Z", "created_at": "2026-08-10T12:00:01Z" },
    { "status": "SENT", "occurred_at": "2026-08-10T12:00:05Z", "created_at": "2026-08-10T12:00:06Z" },
    { "status": "ACCEPTED", "message": "aceito pelo destinatário", "occurred_at": "2026-08-10T12:03:00Z", "created_at": "2026-08-10T12:03:01Z" }
  ]
}

webhook_url é opcional na criação do aceite — se omitido, o recibo simplesmente não é entregue via HTTP, mas o histórico continua disponível por consulta (GET /api/v1/reports/{id}). Se essa consulta for repetida, o espaçamento está em Integração resiliente.

Boas práticas ao receber o webhook

• Responda 2xx rapidamente — processe de forma assíncrona no seu lado, se precisar de trabalho pesado.
• Trate o recebimento como idempotente: pelo desenho do serviço, você não deve receber o mesmo recibo duas vezes para o mesmo acceptance_id, mas seu endpoint deve tolerar reentregas com segurança.
• Use metadata e execution_id para correlacionar o recibo com o registro do seu sistema — o acceptance_id é gerado pelo serviço.

🔍 Consultando o histórico

Listar aceites — GET /api/v1/reports

Filtros opcionais via query string:

O escopo é sempre limitado à sua credencial — você só vê os aceites criados com a sua X-API-Key.

Os filtros status, meta_key/meta_value e acceptance_id são aplicados após a leitura, não como condição de índice. Em volumes altos, prefira filtrar por intervalo de datas (from/to).

Página de referência: Listar Aceites.

Detalhes de um aceite — GET /api/v1/reports/{id}

Retorna o registro completo (mesmo formato de um item da listagem), incluindo a trilha inteira de status. 404 se o acceptance_id não existir ou pertencer a outra credencial.

Página de referência: Detalhes do Aceite.

Próximo passo ➡️

• Collections — acesse a página central de collections dos produtos desta seção.
• Recipe: criar, disparar e consultar um aceite.