Entrega e Reenvio de Webhooks
Esta página descreve o que a QI Tech faz quando a entrega de um webhook falha e os endpoints que permitem consultar o histórico de entregas e forçar um reenvio. Para a lista dos eventos emitidos, consulte Eventos de Escrituração; para cadastrar a URL de destino, Configuração de Webhooks.
Todo evento gerado é registrado antes de ser entregue. A primeira entrega é síncrona, no mesmo instante em que o evento nasce; se ela falhar, o evento entra na fila de reenvio.
Política de reenvio
Uma entrega falha quando o seu endpoint responde com um status 3xx, 4xx ou 5xx, ou quando a requisição não chega a receber resposta (falha de DNS, conexão recusada ou timeout).
Cada evento é entregue no máximo 8 vezes: a tentativa inicial e mais 7 reenvios, com intervalo crescente entre eles.
| Tentativa | Intervalo desde a anterior | Tempo desde a primeira |
|---|---|---|
| 1 | — | 0 |
| 2 | 1 minuto | 1 minuto |
| 3 | 5 minutos | 6 minutos |
| 4 | 15 minutos | 21 minutos |
| 5 | 1 hora | 1h21 |
| 6 | 3 horas | 4h21 |
| 7 | 6 horas | 10h21 |
| 8 | 12 horas | 22h21 |
Esgotadas as 8 tentativas, o evento passa para failed e não é mais enviado.
A fila de reenvio é processada a cada 5 minutos, então o intervalo efetivo pode ser até 5 minutos maior que o da tabela.
Se o seu sistema processar o evento e a resposta não chegar até nós, por timeout ou por um erro posterior ao processamento, a entrega é contada como falha e o evento é reenviado.
O corpo é idêntico em todas as tentativas. O event_datetime marca o momento em que o evento foi gerado, não o do envio, então ele não muda entre as tentativas: use a combinação de event_type, event_datetime e os identificadores de event_data para reconhecer o que você já processou.
Status do webhook
| Status | Descrição |
|---|---|
pending_shipment | A última entrega falhou. O campo next_attempt_at indica quando será a próxima. |
on_queue | Reenvio enfileirado, aguardando processamento. |
sent | Entregue. O seu endpoint respondeu 2xx. |
failed | As 8 tentativas se esgotaram. O evento não será mais enviado. |
Consulta de Webhooks (GET)
Retorna os eventos do seu tenant, do mais recente para o mais antigo. Use esta consulta para reconciliar o que a QI Tech enviou com o que o seu sistema processou.
Request
Query Params
| Campo | Tipo | Descrição |
|---|---|---|
status | string | Filtra pelo status da entrega. Aceita pending_shipment, on_queue, sent ou failed. |
event_type | string | Filtra pelo tipo do evento, por exemplo commercial_paper.operation_status_change. |
created_after | string | Retorna os eventos gerados a partir desta data e hora, no formato YYYY-MM-DDTHH:MM:SS. |
created_before | string | Retorna os eventos gerados até esta data e hora, no mesmo formato. |
page | integer | Página desejada, começando em 1. Padrão 1. |
page_size | integer | Registros por página. Padrão e máximo 100. |
Response
Response Body
{
"data": [
{
"webhook_key": "46804f32-101e-4702-8fbc-c2dbc4c2caec",
"tenant_key": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"status": "pending_shipment",
"number_of_attempts": 2,
"next_attempt_at": "2026-05-05T13:27:01",
"webhook_data": {
"event_type": "commercial_paper.operation_status_change",
"event_datetime": "2026-05-05T13:22:01Z",
"event_data": {
"operation_key": "072a7cc4-1fbf-419b-8a41-f57bd86ee753",
"operation_status": "issued"
}
},
"created_at": "2026-05-05T13:22:01"
}
],
"pagination": {
"current_page": 1,
"next_page": null,
"rows_per_page": 100,
"total_pages": 1,
"total_rows": 1
}
}
Response Body Params
| Campo | Tipo | Descrição |
|---|---|---|
webhook_key | string | Chave única do evento (UUID v4). É o identificador usado no reenvio manual. |
tenant_key | string | Chave do tenant dono do evento. |
status | string | Status atual da entrega. Enumeradores status |
number_of_attempts | integer | Quantidade de entregas que falharam. Uma entrega aceita não incrementa o contador. |
next_attempt_at | string | Data e hora do próximo reenvio. null quando não há reenvio programado. |
webhook_data | object | Corpo enviado ao seu endpoint, idêntico ao da entrega. |
created_at | string | Data e hora em que o evento foi gerado. |
Consulta de um Webhook (GET)
Request
Path Params
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
WEBHOOK-KEY | string | Chave única do evento (UUID v4). | 36 |
Response
Response Body
{
"webhook_key": "46804f32-101e-4702-8fbc-c2dbc4c2caec",
"tenant_key": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"status": "pending_shipment",
"number_of_attempts": 2,
"next_attempt_at": "2026-05-05T13:27:01",
"webhook_data": {
"event_type": "commercial_paper.operation_status_change",
"event_datetime": "2026-05-05T13:22:01Z",
"event_data": {
"operation_key": "072a7cc4-1fbf-419b-8a41-f57bd86ee753",
"operation_status": "issued"
}
},
"created_at": "2026-05-05T13:22:01"
}
Os campos são os mesmos descritos em Response Body Params.
Reenvio Manual (PUT)
Envia o evento na hora, sem esperar a próxima janela da política de reenvio. Serve para quando o seu sistema voltou ao ar antes do próximo intervalo.
A tentativa manual segue as mesmas regras das automáticas: se falhar, incrementa o contador e agenda o próximo degrau; na oitava falha, o evento passa para failed.
Só eventos em pending_shipment ou on_queue podem ser reenviados.
Request
Path Params
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
WEBHOOK-KEY | string | Chave única do evento (UUID v4). | 36 |
Response
A resposta não tem corpo. O 202 confirma que a tentativa foi executada, não que o seu endpoint a aceitou: consulte o evento para saber o resultado.
Erros
| Código HTTP | Código do Erro | Descrição (eng) | Tradução (pt-BR) |
|---|---|---|---|
| 404 | OWB0000001 | Webhook not found. | Webhook não encontrado. |
| 400 | OWB0000005 | You do not have access to this tenant. | Você não tem acesso a este tenant. |
| 409 | OWB0000007 | Webhook is {webhook_status} and cannot be sent again. | O webhook está {webhook_status} e não pode ser reenviado. |
| 409 | OWB0000008 | Webhook is already being sent by another process. | O webhook já está sendo enviado por outro processo. |