Webhooks ou polling? Um acompanhamento de pedidos que se recupera

Use webhooks para mudanças habituais e mantenha consultas de estado para conferir se seus registros correspondem ao painel. Se ainda não possui um receptor público confiável, comece com polling em lotes.

Um pedido pode terminar durante um reinício, e um evento pode chegar duas vezes se a confirmação se perder. Seu acompanhamento deve tratar ambos sem informações antigas ou atualizações duplicadas.

Uma função para cada método

Polling: consultar o estado atual

action=status devolve o estado naquele momento. É possível agrupar até 100 IDs. Consultar mais vezes gera mais requisições, mesmo sem mudanças.

Webhooks: receber mudanças selecionadas

O NotPanel envia eventos à sua URL HTTPS. Eles não usam a cota de requisições status do cliente, mas o receptor precisa de capacidade e monitoramento.

Conciliação: recuperar informações ausentes

Após uma interrupção ou diante de um registro antigo, consulte os pedidos afetados. Eventos podem se perder; as tentativas são limitadas e a entrega não é garantida.

O que a API do NotPanel envia

Adicione um endpoint na página API do seu dashboard ou com webhook.add: uma URL HTTPS pública e os eventos de que precisa, como order.processing, order.in_progress, order.completed, order.partial, order.canceled, order.cancel_refused, refill.completed e refill.rejected; a referência de webhooks lista todos. Guarde o segredo: ele aparece uma única vez e webhook.list nunca o devolve. Consulte seus endpoints com webhook.list, envie um ping de teste com webhook.test e remova um endpoint com webhook.remove.

Cada entrega traz um único evento em um envelope curto: id, type, schema_version, created_at, sequence e data. data.order tem os mesmos campos de uma resposta de action=status. O exemplo abreviado mostra o formato, não um pedido real.

{
  "id": "EXAMPLE_EVENT_ID",
  "type": "order.completed",
  "schema_version": 1,
  "created_at": "2026-10-10T12:30:00Z",
  "sequence": 1042,
  "data": {
    "order": {
      "order": 7001,
      "status": "Completed",
      "status_key": "completed",
      "remains": "0"
    }
  }
}

Leia o tipo de evento no corpo verificado. X-Webhook-Event também é enviado, mas não é assinado. Endpoints criados no dashboard e pela API recebem o mesmo formato.

Receba os eventos com segurança

1. Preserve o corpo original. Verifique X-Webhook-Signature com o segredo e X-Webhook-Timestamp e aplique sua tolerância de tempo. Reconstruir o conteúdo pode alterar os bytes assinados.
2. Registre X-Webhook-Delivery-Id para acompanhar as tentativas; ele é o mesmo em cada nova tentativa dessa entrega. Salve o evento verificado antes de responder 2xx; se não puder aceitá-lo com segurança, permita nova tentativa.
3. Processe cada id de evento uma vez e preserve esse controle após reinícios, junto à atualização do pedido. O mesmo id de evento chega a cada endpoint inscrito nele.
4. Faça tarefas lentas depois da aceitação. A assinatura prova autenticidade, não ordem de chegada. Use sequence para ordenar os eventos e, se um evento atrasado contradiz o estado recente, consulte status antes de substituí-lo.

Guia de verificação de assinaturas

Quando o receptor está indisponível

Um timeout (10 segundos) ou uma resposta fora de 2xx é uma tentativa falha. O NotPanel tenta cada entrega até 8 vezes em 24 horas: na hora e depois 1 minuto, 5 minutos, 30 minutos, 2 horas, 6 horas, 12 horas e 24 horas após o evento. Ele pausa o endpoint após 50 falhas seguidas ou 3 dias sem sucesso e avisa o titular da conta. Uma entrega bem-sucedida zera o contador. Monitore webhook.list: silêncio não prova ausência de mudanças.

Confira periodicamente pedidos pendentes ou antigos em lotes de até 100 IDs, respeitando cabeçalhos e limites. Após reparar o receptor, retome o endpoint na seção de webhooks da página API do seu dashboard, o que zera o contador de falhas. Outra opção é removê-lo com webhook.remove, adicionar de novo a URL HTTPS corrigida com webhook.add e os eventos desejados, guardar o novo segredo com segurança e atualizar a verificação no receptor. A API pública não oferece ação para retomar um endpoint. Entregas pendentes no momento da pausa não são reenviadas, então concilie os estados perdidos com status.

Teste além da entrega bem-sucedida

Use mensagens sintéticas e um segredo próprio para testes; pedidos reais não são necessários.

• A mesma entrega duas vezes deve causar uma atualização.
• O mesmo evento entregue duas vezes, com um reinício no meio, ainda deve ser reconhecido.
• Um byte alterado ou data antiga deve falhar conforme sua política.
• Após interrupção e evento atrasado, status deve recuperar a visão atual.

Selecionar eventos, verificar segredos e confirmar rapidamente também aparece nas recomendações do GitHub. Os cabeçalhos, formatos e limites descritos aqui são os do NotPanel.

Perguntas frequentes

Posso usar apenas polling?

Sim. Agrupe consultas e adapte a frequência ao volume e aos limites. Webhooks não são obrigatórios para criar ou acompanhar pedidos.

Webhooks chegam imediatamente e só uma vez?

Não. Podem atrasar ou se repetir. Verifique cada entrega, processe cada evento uma vez e mantenha consultas de estado para recuperação.

Quais cabeçalhos devo conferir?

X-Webhook-Signature e X-Webhook-Timestamp; depois leia id, type e data do corpo verificado. Use X-Webhook-Delivery-Id apenas para acompanhar as tentativas.

Um webhook protege um add incerto?

São problemas diferentes. Repita o add com request_id original e parâmetros inalterados, depois salve o ID de pedido recuperado.

Referências: contrato de webhooks · estado do pedido · recuperação de timeout.