Logs de Entrega

Cada entrega de webhook fica registrada em um log, com o payload enviado, a resposta do seu servidor e o número de tentativas. Use estas rotas para investigar falhas e reenviar notificações.

---

Listar logs de entrega

GET /v1/webhooks/{webhookId}/logs

URL completa: https://api.tapsign.com.br/v1/webhooks/{webhookId}/logs

Headers

Header	Valor
Authorization	Bearer {token}

Parâmetros de rota

Parâmetro	Tipo	Obrigatório	Descrição
webhookId	integer	Sim	Identificador do webhook

Query parameters

Parâmetro	Tipo	Obrigatório	Descrição
page	integer	Não	Página, começando em 0. Padrão: 0
size	integer	Não	Itens por página. Padrão: 20. Máximo: 100
status	string	Não	SUCCESS, FAILED ou DEAD_LETTER
eventType	string	Não	Nome do evento, por exemplo doc_completed
from	string	Não	Data e hora inicial (ISO 8601, por exemplo 2026-09-01T00:00:00)
to	string	Não	Data e hora final (ISO 8601)

Exemplo de requisição

curl -X GET "https://api.tapsign.com.br/v1/webhooks/7/logs?page=0&size=10&status=FAILED" \
  -H "Authorization: Bearer {token}"

Resposta

Status: 200 OK

{
  "content": [
    {
      "id": 5821,
      "eventType": "doc_completed",
      "envelopeId": 1234,
      "status": "FAILED",
      "attempt": 3,
      "responseStatus": null,
      "responseBody": null,
      "errorMessage": "500 Internal Server Error: \"erro ao processar\"",
      "payload": "{\"event_type\":\"doc_completed\",\"token\":\"3f6c1a52-8d0e-4b8a-9c61-2f7d5e4a1b90\", ...}",
      "createdAt": "2026-09-12T15:35:00Z",
      "nextRetryAt": "2026-09-12T15:41:00Z"
    }
  ],
  "totalElements": 1,
  "totalPages": 1,
  "size": 10,
  "number": 0
}

Campos do log

Campo	Tipo	Descrição
id	integer	Identificador do log
eventType	string	Evento entregue
envelopeId	integer	ID numérico do envelope que gerou o evento
status	string	SUCCESS, FAILED (ainda pode ser retentado) ou DEAD_LETTER (tentativas esgotadas)
attempt	integer	Número de tentativas feitas até agora
responseStatus	integer ou null	Status HTTP recebido do seu servidor. Fica null quando a entrega falha com resposta 4xx ou 5xx, timeout ou erro de conexão
responseBody	string ou null	Corpo da resposta do seu servidor, truncado em 2.000 caracteres
errorMessage	string ou null	Motivo da falha, truncado em 2.000 caracteres
payload	string	JSON exato que foi enviado (o mesmo usado no cálculo da assinatura)
createdAt	string	Data da primeira tentativa (ISO 8601, UTC)
nextRetryAt	string ou null	Próxima tentativa agendada, quando houver

Detalhar um log

GET /v1/webhooks/{webhookId}/logs/{logId}

Retorna um único log, com os mesmos campos da listagem.

curl -X GET "https://api.tapsign.com.br/v1/webhooks/7/logs/5821" \
  -H "Authorization: Bearer {token}"

---

Reenviar entrega

Reenvia na hora o payload guardado no log e devolve o log atualizado.

POST /v1/webhooks/{webhookId}/logs/{logId}/retry

URL completa: https://api.tapsign.com.br/v1/webhooks/{webhookId}/logs/{logId}/retry

Exemplo de requisição

curl -X POST "https://api.tapsign.com.br/v1/webhooks/7/logs/5821/retry" \
  -H "Authorization: Bearer {token}"

Resposta

Status: 200 OK, com o mesmo log: attempt aumenta em 1 e status passa para SUCCESS ou continua FAILED.

{
  "id": 5821,
  "eventType": "doc_completed",
  "envelopeId": 1234,
  "status": "SUCCESS",
  "attempt": 4,
  "responseStatus": 200,
  "responseBody": "ok",
  "errorMessage": "500 Internal Server Error: \"erro ao processar\"",
  "payload": "{\"event_type\":\"doc_completed\", ...}",
  "createdAt": "2026-09-12T15:35:00Z",
  "nextRetryAt": null
}

Limites do reenvio manual

• No máximo 10 reenvios manuais por minuto por webhook. Acima disso a API responde 400.
• A rota também tem rate limit próprio de 10 requisições por minuto.
• O reenvio usa o payload original. Se ele traz signed_file, o link pode já ter expirado (validade de 24 horas).

---

Estatísticas de entrega

Resumo de todas as entregas registradas para o webhook.

GET /v1/webhooks/{webhookId}/logs/stats

URL completa: https://api.tapsign.com.br/v1/webhooks/{webhookId}/logs/stats

Exemplo de requisição

curl -X GET "https://api.tapsign.com.br/v1/webhooks/7/logs/stats" \
  -H "Authorization: Bearer {token}"

Resposta

Status: 200 OK

{
  "totalDeliveries": 1520,
  "successCount": 1487,
  "failedCount": 21,
  "deadLetterCount": 12,
  "successRate": 97.83,
  "lastDeliveryAt": "2026-09-12T16:00:05Z",
  "lastSuccessAt": "2026-09-12T16:00:05Z",
  "lastFailureAt": "2026-09-11T09:12:40Z"
}

Campo	Tipo	Descrição
totalDeliveries	integer	Total de logs de entrega do webhook
successCount	integer	Logs com status SUCCESS
failedCount	integer	Logs com status FAILED
deadLetterCount	integer	Logs com status DEAD_LETTER
successRate	number	Percentual de sucesso (0 a 100)
lastDeliveryAt	string ou null	Data da última entrega
lastSuccessAt	string ou null	Data da última entrega com sucesso
lastFailureAt	string ou null	Data da última falha

---

Erros comuns

Status	Quando acontece
400	Mais de 10 reenvios manuais no mesmo minuto para o webhook, ou size acima de 100
401	Token ausente ou inválido
404	Webhook inexistente ou de outro usuário, ou log que não pertence ao webhook
429	Rate limit da rota excedido