Webhooks públicos: envie eventos de pedidos, expedições e faturas para o seu próprio sistema

Assine os eventos do Docklify —pedido criado, pedido atendido, expedição entregue à transportadora, fatura emitida, entrega concluída— e receba-os como envios HTTPS assinados no seu próprio endpoint, com eventos de teste, novas tentativas automáticas e log de entregas.

Os webhooks públicos transformam o que acontece no Docklify em mensagens para o seu próprio sistema. Assim que um pedido é criado, uma expedição é entregue à transportadora ou uma fatura é emitida, o Docklify envia um post HTTPS para um endereço que você controla. Usos típicos: sincronizar pedidos com o seu ERP ou software contábil, avisar os seus clientes com as suas palavras, alimentar os seus painéis ou disparar um processo posterior sem consultar uma API.

Eventos que você pode assinar#

• order.created: um pedido de venda é criado (manual, portal do cliente ou conversão de CRM).
• order.allocated: um pedido é alocado e o estoque fica reservado.
• order.fulfilled: um pedido é totalmente atendido; inclui código de rastreio e transportadora.
• order.cancelled: um pedido é cancelado; inclui o código do motivo.
• order.delivered: um pedido é marcado como entregue.
• shipment.fulfilled: uma expedição do WMS é entregue à transportadora; inclui o código de rastreio.
• receipt.completed: um recebimento de entrada é concluído, com todas as linhas recebidas.
• inventory.adjusted: o estoque é ajustado diretamente num local.
• invoice.issued: uma fatura a receber é gerada. As novas nascem como rascunho; o campo de status mostra o estado atual.
• delivery.completed: uma entrega de última milha é assinada e concluída, com a prova de entrega capturada.
• test.ping: o evento de teste. Envie quando quiser para verificar se o seu endpoint responde e se a verificação de assinatura funciona.

Criar uma assinatura#

1. Abra Integration → Webhooks e clique em Nova assinatura.
2. Nome: dê um nome que a sua equipe reconheça, por exemplo “Sincronização ERP”.
3. URL: o endereço https do seu servidor que receberá os eventos. Deve usar https e resolver para um endereço público: endereços privados, de rede local ou de loopback são rejeitados.
4. Eventos: marque os eventos que você quer. Você pode mudar a seleção quando quiser.
5. Salve e copie o segredo de assinatura: começa com whsec_. Guarde-o na configuração do seu servidor; você precisa dele para verificar se as entregas vêm mesmo do Docklify. Você pode vê-lo de novo, ou rotacioná-lo, na página de Webhooks quando quiser.

O que o seu receptor deve fazer#

Cada entrega é um post HTTPS com um corpo JSON: o envelope. O envelope diz o que aconteceu (type), quando (created_at) e traz os detalhes em data:

{
  "id": "<event id>",
  "type": "order.fulfilled",
  "created_at": "2026-10-20T12:00:00.000Z",
  "organization_id": "<your organization id>",
  "data": {
    "order_id": "<order id>",
    "order_no": "SO-1001",
    "status": "fulfilled",
    "tracking_number": "<tracking number>",
    "carrier_code": "ups"
  }
}

• Deduplique por id: a entrega é “pelo menos uma vez”. As novas tentativas e os reenvios manuais reutilizam o mesmo id de evento: guarde os ids processados e pule os repetidos.
• Responda 2xx, e responda rápido: qualquer 2xx conta como sucesso. As entregas expiram em 10 segundos; se o seu processo for lento, guarde primeiro o evento, responda 200 e processe depois.
• Qualquer outra coisa conta como falha: um status não 2xx, um redirecionamento (o 3xx não é seguido), um tempo esgotado ou um endereço inalcançável; tudo dispara as novas tentativas automáticas descritas abaixo.

Verificar a assinatura#

Qualquer pessoa que conheça a sua URL poderia enviar eventos falsos, por isso cada entrega é assinada: verifique a assinatura antes de confiar nos dados. A especificação completa (nomes dos cabeçalhos, o algoritmo exato e exemplos de uma linha em Node e Python) está na documentação da API, na seção Webhooks. Os pontos principais:

• Cada entrega traz o cabeçalho X-Docklify-Signature, no formato t=<segundos unix>,v1=<hex>. A mesma entrega traz também X-Docklify-Event (o tipo de evento) e X-Docklify-Delivery (o id da entrega).
• v1 é o HMAC-SHA256 em hex da cadeia “<t>.<corpo original>”, usando o seu segredo de assinatura como chave.
• Calcule sempre sobre o corpo original da requisição, exatamente como chegou. Nunca interprete o JSON e o serialize de novo: os espaços e a ordem das chaves mudam, e a assinatura não vai bater.
• Se a assinatura não bater, não processe o evento.

Enviar um evento de teste#

1. Em Integration → Webhooks, abra a sua assinatura e escolha Enviar evento de teste.
2. O Docklify entrega na hora um test.ping para a sua URL. Os eventos de teste podem ser enviados a qualquer assinatura, embora o test.ping nunca esteja na lista de eventos dela.
3. Confira o log de entregas: uma linha como entregue, mais a assinatura verificada no seu servidor, significa que você está pronto para os eventos reais.

Log de entregas e solução de problemas#

Cada entrega fica registrada no log de entregas (Integration → Webhooks → Entregas): o tipo de evento, o status (pendente, entregue ou falhou), quantas tentativas foram feitas, o último código HTTP e erro, e o horário da próxima tentativa. Uma entrega que falhou é repetida automaticamente após 1 minuto, 5 minutos, 30 minutos, 2 horas e 6 horas: seis tentativas no total. Depois da última, ela fica como falhada até você reenviá-la manualmente pelo log; o reenvio reutiliza o mesmo id de evento, então a sua deduplicação mantém tudo seguro.

• Endereço inalcançável: o seu servidor está fora do ar, a URL está errada ou o nome não resolve para um endereço público. Corrija o endpoint e reenvie pelo log.
• Problemas de certificado: um certificado TLS vencido ou autoassinado faz a entrega falhar. Use um certificado válido de uma autoridade pública.
• Resposta não 2xx: o seu receptor falhou ou rejeitou o evento. Leia o código e o erro no log, corrija a causa e reenvie.
• Tempo esgotado: o seu receptor demorou mais de 10 segundos. Responda 2xx primeiro e faça o trabalho pesado em segundo plano.
• A assinatura não bate do seu lado: costuma ser um corpo resserializado, ou um segredo antigo ainda em uso após uma rotação; ver Verificar a assinatura acima.

Pausar uma assinatura e rotacionar o segredo#

• Pausar: coloque a assinatura como Pausada na página de Webhooks. Enquanto estiver pausada, o Docklify não entrega eventos novos a ela. Retome quando quiser: pausar é a forma segura de tirar um endpoint do ar para manutenção.
• Rotacionar o segredo: se um segredo pode ter vazado, ou um colega que o conhecia saiu, rotacione-o na página da assinatura. Após a rotação, as entregas são assinadas só com o segredo novo, então atualize o seu servidor no mesmo momento: um receptor com o segredo antigo vai rejeitar as entregas novas.