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

Este guia cobre registros via webhook.add: URL HTTPS pública e eventos aceitos, como order.processing, order.in_progress, order.completed, order.partial, order.refunded e order.refill_completed. Guarde o segredo; webhook.list não o devolve. Consulte estado e falhas com webhook.list e remova registros com webhook.remove.

Entregas da API incluem events, mesmo com um único evento. Cada item tem id, event, timestamp e data; deliveryId identifica a entrega. O exemplo abreviado é ilustrativo, e suas datas antigas não servem para testar a tolerância de tempo.

{
  "events": [
    {
      "id": "EXAMPLE_EVENT_ID",
      "event": "order.completed",
      "timestamp": 1700000000,
      "data": { "order": 7001, "status_key": "completed" }
    }
  ],
  "timestamp": 1700000001,
  "deliveryId": "EXAMPLE_DELIVERY_ID"
}

Leia o evento no corpo verificado: lotes da API não exigem X-Webhook-Event. Webhooks criados no dashboard usam outro formato com evento único; não trate os dois formatos como iguais.

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. Confira se X-Webhook-Delivery-Id corresponde ao deliveryId do corpo assinado. Salve a entrega antes de responder 2xx; se não puder aceitá-la com segurança, permita nova tentativa.
3. Processe cada events[].id uma vez e preserve esse controle após reinícios, junto à atualização do pedido. O mesmo evento pode chegar por endpoints diferentes.
4. Faça tarefas lentas depois da aceitação. A assinatura prova autenticidade, não ordem de chegada. 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

Timeout ou resposta fora de 2xx conta como falha. O NotPanel repete com intervalos crescentes e pausa o endpoint API após 10 falhas consecutivas; 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 um receptor pausado, confirme que seu registro está ativo. Não presuma reenvio automático de todas as entregas históricas que falharam.

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.
• Um evento em dois lotes e um reinício não devem duplicá-lo.
• 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 compare X-Webhook-Delivery-Id ao deliveryId do corpo verificado e processe seu array events.

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.