Webhooks DataFirefly: guia completo

Apresentação

Os Webhooks DataFirefly ligam a sua loja PrestaShop 8 e 9 a mais de 5000 aplicações, nos dois sentidos. Em saída, a sua loja emite os seus eventos (encomendas, clientes, stock e outros) para o Zapier, o Make, o n8n ou qualquer endpoint HTTP. Em entrada, essas mesmas ferramentas podem enviar dados para a loja através de uma API segura.

O módulo assenta em três pilares: uma fila de espera assíncrona (sem encomendas atrasadas), repetições automáticas com recuo exponencial, e uma assinatura HMAC-SHA256 para garantir a autenticidade das mensagens.

Instalação

1. Descarregue o arquivo dfwebhooks.zip a partir da sua conta DataFirefly.
2. No back-office, vá a Módulos > Gestor de módulos > Carregar um módulo e coloque o ZIP.
3. Clique em Instalar e depois em Configurar.
4. Chega ao ecrã principal, que mostra o URL do worker de cron e o URL da API de entrada.

1. Agendar o worker de cron (fluxo de saída)

Os webhooks de saída não são enviados de imediato: são colocados em fila e entregues por um worker que aciona periodicamente. Copie o URL do cron apresentado no ecrã de configuração e agende-o de 1 em 1 a 5 em 5 minutos.

*/2 * * * * curl -s "https://a-sua-loja.pt/index.php?fc=module&module=dfwebhooks&controller=cron&token=O_SEU_TOKEN" >/dev/null 2>&1

Em cada passagem, o worker trata até 50 entregas em espera, aplica as repetições necessárias e limpa os registos antigos conforme a duração de retenção configurada.

2. Criar um endpoint de saída

Um endpoint liga um evento a um URL de destino. No ecrã principal, clique em Adicionar e preencha:

• Nome: uma designação interna (por exemplo, «Nova encomenda → Zapier»).
• Evento: o evento que aciona o envio (ver a lista mais abaixo).
• URL: cole o URL «Catch Hook» do Zapier ou «Custom Webhook» do Make.
• Segredo de assinatura (opcional): se estiver preenchido, cada payload é assinado em HMAC-SHA256.

Filtros condicionais

Pode enviar um webhook apenas quando certas condições estiverem reunidas. As regras estão em formato JSON e combinam-se com E lógico. Operadores disponíveis: eq, neq, gt, gte, lt, lte, in e contains.

[{"field":"order.total_paid","op":"gte","value":100}]

Este exemplo só aciona o webhook nas encomendas cujo total pago seja igual ou superior a 100.

Mapeamento de campos

Por predefinição, é enviado o payload completo. Para enviar apenas certos campos com um formato preciso, defina um mapeamento: a chave é o nome de saída e o valor é o caminho dentro do payload.

{"email":"customer.email","total":"order.total_paid"}

3. Eventos de saída disponíveis

• order.created: uma encomenda acabou de ser validada.
• order.status.updated: o estado de uma encomenda mudou.
• order.refunded: uma encomenda passou ao estado de reembolsada.
• customer.created: um novo cliente registou-se.
• address.created: foi criada uma nova morada.
• product.created: foi acrescentado um produto.
• product.updated: um produto foi alterado.
• product.stock.low: o stock desceu abaixo do limiar configurado.
• review.created: uma avaliação foi validada (exige um módulo de avaliações compatível).

4. API de entrada (Zapier/Make/n8n para o PrestaShop)

A API de entrada permite às suas automatizações alterar a loja. Está protegida por um token e, opcionalmente, por uma assinatura HMAC.

Criar um token

No painel Tokens de entrada, dê uma designação, escolha os âmbitos autorizados (orders, products, customers) e, se quiser, um segredo de assinatura. O token gerado é para colar na sua ferramenta.

Enviar um pedido

Faça um POST para o URL da API de entrada. O token vai no cabeçalho X-DF-Token (ou no parâmetro ?token=). O corpo é um JSON com uma action e um objeto data.

POST https://a-sua-loja.pt/index.php?fc=module&module=dfwebhooks&controller=api
X-DF-Token: O_SEU_TOKEN
Content-Type: application/json

{"action":"order.status.update","data":{"id_order":42,"id_order_state":4}}

5. Ações de entrada disponíveis

• order.status.update (âmbito orders): muda o estado de uma encomenda. Campos: id_order, id_order_state e send_email (opcional).
• order.get (âmbito orders): obtém uma encomenda. Campo: id_order.
• product.stock.update (âmbito products): fixa o stock. Campos: id_product, quantity e id_product_attribute (opcional).
• product.upsert (âmbito products): cria ou atualiza um produto pela sua reference.
• customer.upsert (âmbito customers): cria ou atualiza um cliente pelo seu email.
• customer.get (âmbito customers): obtém um cliente por email ou id_customer.

6. Verificar a assinatura HMAC

Se estiver configurado um segredo no endpoint (saída) ou no token (entrada), a mensagem leva um cabeçalho X-DF-Signature: sha256=.... Para o verificar do lado da receção, recalcule o HMAC do corpo em bruto com o seu segredo e compare em tempo constante.

$expected = "sha256=" . hash_hmac("sha256", $rawBody, $secret);
if (hash_equals($expected, $signatureHeader)) {
    // assinatura válida
}

Compare sempre o HMAC calculado sobre o corpo em bruto (não voltado a serializar), sob pena de a assinatura não corresponder.

7. Registo de entregas e reenvio

O menu Webhooks Delivery Log lista cada tentativa com o seu estado:

• SENT: entregue com um código HTTP 2xx.
• PENDING: em fila, à espera da próxima passagem do worker.
• FAILED: falha temporária, com uma repetição agendada.
• DEAD: falha definitiva ao fim de 6 tentativas.

As repetições seguem um recuo exponencial: 1 minuto, 5 minutos, 30 minutos, 2 horas e depois 6 horas. Pode forçar um novo envio a qualquer momento com o botão Replay, e inspecionar o payload exato pela ação Ver.

8. Multiloja, RGPD e modo em lote

Cada endpoint e cada token estão associados a uma loja concreta: os fluxos de uma loja nunca passam para outra. A opção Anonimizar os dados pessoais oculta e-mails, telefones e nomes antes do envio, para respeitar o RGPD quando o destino não deve receber dados nominativos. O modo em lote agrupa os envios para grandes volumes.

Perguntas frequentes e resolução de problemas

Não é enviado qualquer webhook. Confirme que o worker de cron está mesmo agendado e que o seu URL (com o token certo) responde. Consulte o registo: se as linhas ficarem em PENDING, é porque o cron não está a correr.

O endpoint remoto devolve um erro 401 ou 403. A sua ferramenta pode estar à espera de uma verificação de assinatura: preencha o mesmo segredo dos dois lados, ou retire-o durante os testes.

A API de entrada devolve «insufficient_scope». O token usado não tem o âmbito exigido pela ação. Altere o token para assinalar o âmbito correspondente (orders, products ou customers).

A página de teste mostra uma falha. O botão Testar envia um payload de exemplo em modo síncrono: uma falha indica normalmente um URL inacessível ou um certificado TLS inválido do lado do destino.