Entregas, falhas e reenvio

O que conta como sucesso, a tabela de retentativas, desativação por inatividade e a API de gestão.

O que conta como sucesso

Qualquer resposta HTTP 2xx no POST da entrega é sucesso. Qualquer outra coisa conta como falha: 3xx (redirect não é seguido), 4xx, 5xx, timeout (10 segundos) e erro de rede/DNS/TLS. O corpo da sua resposta não é interpretado — só o status.

Retentativas

Uma entrega que falha é tentada de novo com backoff exponencial, por até 24 horas desde a primeira tentativa (ou desde um reenvio manual, que abre uma janela nova — veja abaixo):

Tentativa	Espera até a próxima
1ª falha	2s
2ª falha	4s
3ª falha	8s
4ª falha	16s
5ª falha	32s
6ª falha	1min
7ª falha	2min
8ª falha	5min
9ª falha	10min
10ª falha	20min
11ª falha	30min
12ª falha em diante	1h (repete até completar 24h)

Depois de 24h sem sucesso, a entrega vira FAILED e só volta a ser tentada com um reenvio manual.

Desativação do endpoint por inatividade

Na primeira falha depois de um período de sucesso, o endpoint começa a "falhar" (fica marcado internamente, sem mudar de status) e um e-mail é enviado aos membros OWNER/ADMIN do workspace avisando que o endpoint está com problema.
Se o endpoint passar 5 dias corridos sem nenhuma entrega bem-sucedida, ele vira DISABLED_FAILING: todas as entregas pendentes são canceladas e um segundo e-mail avisa a desativação.
Um workspace sem acesso operacional (assinatura suspensa, trial expirado etc.) tem as entregas pausadas sem gastar tentativa até o acesso ser restaurado — isso não conta como falha para o prazo de 5 dias.
Para reativar, use o botão "Reativar" na UI ou POST /endpoints/:id/enable. O endpoint volta para ACTIVE e o contador de inatividade zera no próximo sucesso.

Log de entregas e retenção

Cada endpoint tem um log de entregas com as tentativas, status HTTP recebido, erro (quando houver) e duração. A tela faz polling a cada 10s para refletir o worker em andamento.

Metadados (status, tentativas, timestamps) ficam por 30 dias.
Corpo da requisição e da resposta ficam por 7 dias; depois disso o conteúdo é anulado, mas a linha do log continua existindo com os metadados.

Reenvio manual

Reenviar uma entrega (botão "Reenviar" ou POST /deliveries/:id/resend) reusa o corpo já gravado — por isso só funciona enquanto o corpo existir (até 7 dias após a entrega original). O reenvio abre uma janela nova de 24h de retentativas e não some com o histórico de tentativas anteriores.

Condições para reenviar:

o endpoint precisa estar ACTIVE;
a entrega precisa estar num estado terminal (SUCCEEDED, FAILED ou CANCELLED) — não dá para reenviar uma entrega que ainda está PENDING/SENDING, o worker já está cuidando dela.

Evento de teste

POST /endpoints/:id/test dispara um evento de exemplo do tipo escolhido, assinado de verdade com o segredo do endpoint, com "test": true no envelope — útil para validar a integração sem esperar o evento real acontecer.

Gerenciar pela API

Para integradores (n8n, Make, scripts próprios), toda a gestão de endpoints e entregas também está disponível por API key, com o escopo webhooks:manage:

https://vensy.com.br/api/v1/integrations/webhooks

Sem referência OpenAPI gerada ainda

Estas rotas ainda não aparecem no contrato OpenAPI público nem na Referência da API gerada a partir dele — a tabela abaixo é o contrato até essa referência ser publicada.

Endpoints

Método	Caminho	Uso
`POST`	`/endpoints`	Cria um endpoint. Devolve o segredo em texto puro uma única vez.
`GET`	`/endpoints`	Lista os endpoints do workspace.
`GET`	`/endpoints/{id}`	Detalhe de um endpoint (sem o segredo).
`PATCH`	`/endpoints/{id}`	Atualiza URL, descrição, eventos, headers ou status (`ACTIVE`/`PAUSED`).
`DELETE`	`/endpoints/{id}`	Exclui o endpoint.
`POST`	`/endpoints/{id}/regenerate-secret`	Gera um segredo novo e invalida o anterior na hora.
`POST`	`/endpoints/{id}/test`	Envia um evento de teste assinado.
`POST`	`/endpoints/{id}/enable`	Reativa um endpoint `DISABLED_FAILING`.
`GET`	`/endpoints/{id}/deliveries`	Log de entregas do endpoint.

Entregas

Método	Caminho	Uso
`GET`	`/deliveries/{id}`	Detalhe de uma entrega, com as tentativas.
`POST`	`/deliveries/{id}/resend`	Reenvia (reusa o corpo gravado).

Catálogo

Método	Caminho	Uso
`GET`	`/event-types`	Lista os tipos de evento disponíveis para assinar.

Criar um endpoint

curl -X POST https://vensy.com.br/api/v1/integrations/webhooks/endpoints \
  -H "Authorization: Bearer vsk_live_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://meu-n8n.exemplo.com/webhook/vensy",
    "description": "Fluxo n8n de negócios",
    "eventTypes": ["deal.*", "contact.created"],
    "headers": { "X-Minha-Chave": "valor-secreto" }
  }'

A resposta traz secret em texto puro — a única vez que ele aparece. eventTypes aceita até 50 entradas por endpoint; headers aceita até 10 headers customizados.

Erros

Código	Status	Quando acontece
`WEBHOOK_ENDPOINT_LIMIT_REACHED`	`409`	O workspace já tem o número máximo de endpoints (10 por padrão).
`WEBHOOK_URL_FORBIDDEN`	`400`	A URL não é HTTPS, ou resolve para um host/IP privado (anti-SSRF).
`WEBHOOK_EVENT_TYPE_INVALID`	`400`	Um ou mais itens de `eventTypes` não existem no catálogo (nem como tipo exato nem como família válida).
`WEBHOOK_HEADER_INVALID`	`400`	Um header customizado tem nome inválido, nome reservado (`webhook-*`, `content-type`...) ou valor com quebra de linha.
`WEBHOOK_ENDPOINT_NOT_FOUND`	`404`	O endpoint não existe (ou pertence a outro workspace).
`WEBHOOK_DELIVERY_NOT_FOUND`	`404`	A entrega não existe (ou pertence a outro workspace).
`WEBHOOK_DELIVERY_BODY_EXPIRED`	`409`	Tentou reenviar uma entrega cujo corpo já passou dos 7 dias de retenção.
`WEBHOOK_ENDPOINT_NOT_ACTIVE`	`409`	Tentou reenviar uma entrega de um endpoint que não está `ACTIVE`.
`WEBHOOK_DELIVERY_IN_PROGRESS`	`409`	Tentou reenviar uma entrega que ainda não chegou a um estado terminal.

Consulte também o catálogo geral de erros para os códigos comuns a toda a API (API_KEY_INVALID, API_KEY_SCOPE_REQUIRED, validação, etc.).

Nesta página