Markdown
Referência · fila

Entregas do webhook

Consulte as tentativas de entrega ao seu endpoint e recupere eventos que falharam.

Cada evento enfileirado tem uma entrega. As tentativas atualizam a mesma linha, mantendo seu identificador. Consulte se o endpoint aceitou, confira a última resposta e reenvie falhas.

Listar (link para esta seção)

GET/public/v1/deliveries
ParâmetroO que é
statuspending, delivering, delivered ou failed. Sem ele, vêm todas.
limitAté 200 por página. Padrão 50.
before_idCursor: traz o que é anterior a esse id. Use o next_before_id da resposta.
curl
curl "https://api.patrociniotech.com/public/v1/deliveries?status=failed&limit=100" \
  -H "Authorization: Bearer SUA_CHAVE"
resposta
{
  "success": true,
  "data": {
    "deliveries": [
      {
        "id": 1841,
        "event": "message.status",
        "status": "failed",
        "attempts": 7,
        "last_status": 502,
22 linhas
Para consultar a próxima página, envie o next_before_id recebido como before_id. Mantenha os filtros e continue até o cursor ser nulo.

Ver uma entrega (link para esta seção)

GET/public/v1/deliveries/{id}

Igual à listagem, mais last_error: um resumo da falha ou um trecho da última resposta, guardado mesmo em sucesso. Credenciais conhecidas são ocultadas. Não devolva dados sensíveis no corpo do seu endpoint.

Uma resposta 2xx confirma o recebimento HTTP. Se o evento não produziu o resultado esperado, confira também os registros de processamento no seu sistema.
curl
curl "https://api.patrociniotech.com/public/v1/deliveries/1841" \
  -H "Authorization: Bearer SUA_CHAVE"

Reenviar (link para esta seção)

POST/public/v1/deliveries/{id}/retry

Devolve a entrega para a fila. Vale para failed (esgotou as tentativas) e para delivered (reprocessar do seu lado). O corpo é assinado de novo no disparo, com o timestamp do momento, então uma entrega reenviada horas depois não esbarra na janela de replay do seu endpoint.

O reenvio mantém delivery_id e o histórico de tentativas. Se o evento já foi aplicado, a deduplicação deve continuar impedindo efeitos repetidos. Para refazer uma operação de negócio, use seu próprio processo de recuperação; reenviar o webhook não cria outro evento.
curl
curl -X POST "https://api.patrociniotech.com/public/v1/deliveries/1841/retry" \
  -H "Authorization: Bearer SUA_CHAVE"
POST/public/v1/deliveries/retry-failed

Recoloca até 500 entregas com falha na fila por chamada. Devolve requeued com quantas voltaram. Corrija o endpoint antes de usar; se houver mais registros, confira a fila novamente antes de solicitar outro lote.

curl
curl -X POST "https://api.patrociniotech.com/public/v1/deliveries/retry-failed" \
  -H "Authorization: Bearer SUA_CHAVE"

Rotina sugerida (link para esta seção)

Consulte falhas periodicamente e avise a equipe responsável. O exemplo abaixo verifica uma página da fila; não solicita reenvio automaticamente.

Node.js
async function varrerFalhas() {
  const r = await fetch(`https://api.patrociniotech.com/public/v1/deliveries?status=failed&limit=200`, {
    headers: { Authorization: `Bearer ${process.env.PT_API_KEY}` },
  });
  const { data } = await r.json();
  if (!r.ok || !data?.deliveries) throw new Error("Falha ao consultar as entregas.");
  if (!data.deliveries.length) return;

  // alertar é uma função do seu sistema. Confirme a recuperação antes do reenvio.
  await alertar(`${data.deliveries.length} entregas de webhook falharam`);

  // Após confirmar a recuperação do endpoint, solicite o reenvio em uma ação separada.
}

Situações (link para esta seção)

statusO que significa
pendingNa fila, esperando a próxima tentativa.
deliveringUma tentativa de entrega está em andamento.
deliveredSeu endpoint respondeu 2xx. Isso não confirma o processamento da operação no seu sistema.
failedTentativas esgotadas ou webhook desativado/removido. Consulte last_error antes de reenviar.

next_attempt_at só representa um agendamento ativo quando o estado é pending. Nos demais estados pode conservar o horário da tentativa anterior. delivered_at registra uma aceitação anterior e não substitui o estado atual depois de um reenvio manual.