IMEDIATO
Entrega inicial + tentativa 1
Primeira entrega no evento. Se 5xx ou timeout, nova tentativa 30 segundos depois.
PROGRAMADORES - REFERÊNCIA DE WEBHOOKS
Encomendar eventos do ciclo de vida, assinados e com segurança de repetição.
Os webhooks são acionados em todas as transições de estado das encomendas: recebidas, impressas, expedidas, falhadas. JSON sobre HTTPS, HMAC-SHA256 assinado para verificação, fila de repetição com exponencial até 24 horas. Referência do evento, exemplos de código de verificação de assinatura e política de retry / dead-letter abaixo.
HMAC-SHA256 SIGNED - PELO MENOS UMA VEZ - 24 horas de resposta - Fila de espera de cartas mortas
TIPOS DE EVENTOS
Cinco eventos do ciclo de vida da encomenda.
Subscrever qualquer subconjunto no PUT /v1/account/webhook
endpoint. A maioria das integrações subscreve todas as cinco.
| Evento | Dispara quando | Ação típica |
|---|---|---|
| ordem.recebida | O Fabrixa aceitou a encomenda e atribuiu um order_id. Ack em segundos após o POST. | Atualizar o estado das encomendas internas para "em produção"; superfície para o cliente final. |
| ordem.impressa | Etapa de impressão reactiva concluída. A peça de vestuário passa para o corte e costura. Etapa intermédia de produção. | Opcional - algumas equipas utilizam-no para mensagens de correio eletrónico do cliente final a dizer "a sua encomenda está a ser feita". |
| ordem.expedida | Qualidade verificada, embalada e entregue à transportadora. Emissão do número de seguimento. | Atualizar o estado da encomenda para "expedida"; acionar a notificação de expedição do cliente final com o URL de seguimento. |
| ordem.entregue | A transportadora confirmou a entrega no endereço do destinatário. | Acionar fluxos pós-compra: pedido de revisão, upsell de produtos relacionados, etc. |
| ordem.falhada | A encomenda não pode ser concluída - arte inacessível, endereço do destinatário inválido, tecido fora de stock durante um período prolongado. | Abrir bilhete / notificar as operações. A carga útil inclui erro.código para a lógica de ligação. |
FORMA DE CARGA
O mesmo envelope, dados específicos do evento.
Envelope comum (evento, order_id, order_ref, timestamp) mais um envelope específico do evento
dados objeto. Consumir primeiro o envelope; ligar evento para a forma dos dados.
ordem.expedida
# order.dispatched payload - POST para o seu URL de webhook POSTAR /seu-webhook-endpoint Tipo de conteúdo: aplicação/json X-Fabrixa-Evento: order.dispatched X-Fabrixa-Assinatura: t=1715173928,v1=ab3c4... X-Fabrixa-Delivery-Id: del_94kQ7r2L { "evento": "order.dispatched", "order_id": "ord_8e6f4b2a", "order_ref": "shopify-1042", "carimbo de data/hora": "2026-05-15T11:32:08Z", "production_hub": "PT", "dados": { "rastreio": { "transportadora": "DHL", "tracking_number": "JJD0123456789", "tracking_url": "https://dhl.com/track/JJD0123456789", "estimated_delivery" (entrega estimada)": "2026-05-19" }, "destinatário": { "nome": "Lena Costa", "cidade": "Porto", "país": "PT" } } }
VERIFICAÇÃO DA ASSINATURA
HMAC-SHA256 sobre (carimbo de data/hora + corpo bruto).
Verificar a assinatura antes do processamento. Utilizar o corpo do pedido em bruto - e não um objeto JSON re-serializado - ou o HMAC não corresponderá. O segredo de assinatura é emitido uma vez quando se configura o URL do webhook; rodar através do painel de controlo.
verificar-assinatura.js
// Exemplo de Node.js / Express const cripto = exigir("cripto"); app.posto("/webhook", expresso.bruto({ type: "application/json" }), (req, res) => { const assinatura = req.headers["x-fabrixa-signature"]; const [tPart, v1Part] = assinatura.dividir(","); const timestamp = tPart.dividir("=")[1]; const received = v1Part.dividir("=")[1]; // Rejeitar eventos com mais de 5 minutos (proteção contra repetição) se (Matemática.abs(Data.agora() / 1000 - timestamp) > 300) retorno res.estatuto(400).fim(); const payload = `${timestamp}.${req.body.toString()}`; const esperado = cripto .criarHmac("sha256", process.env.FABRIXA_WEBHOOK_SECRET) .atualização(carga útil) .resumo("hexadecimal"); se (!crypto.timingSafeEqual(Tampão.de(recebido), Buffer.de(esperado))) { retorno res.estatuto(401).fim(); } // Assinatura válida - processar o evento const evento = JSON.analisar(req.body); handleEvent(event); res.estatuto(200).fim(); });
Amostras equivalentes para Python (Flask), PHP, Ruby e Go estão na pasta de scripts da coleção Postman. timingSafeEqual importa - não utilizar a igualdade de cadeias de caracteres, pois é vulnerável a ataques temporais.
POLÍTICA DE REGRESSO
Backoff exponencial até 24 horas.
A entrega do webhook é feita pelo menos uma vez. Se o seu ponto de extremidade retornar 5xx ou o tempo limite (tempo limite de 10s), tentamos novamente em uma programação de backoff exponencial por até 24 horas. Após 24 horas de falha, o evento cai numa fila de cartas mortas que pode reproduzir manualmente.
RETROCESSO
Repetições 2-8, exponencial
60s → 5min → 30min → 2h → 6h → 12h → 24h. Cada nova tentativa espera mais tempo.
CARTA MORTA
Após 24 horas de falha
Evento movido para a fila de cartas mortas. Reproduzir manualmente através do painel de controlo ou POST /v1/webhooks/replay/:delivery_id.
EVENTO ORDER.FAILED
Motivos de erro estruturados para a lógica de ativação.
O evento mais importante do ponto de vista operacional. A carga útil inclui um erro.código string - seguro para ativar o encaminhamento automático, a criação de bilhetes ou o envio de mensagens ao cliente final.
ordem.falhada
{
"evento": "order.failed",
"order_id": "ord_8e6f4b2a",
"order_ref": "shopify-1042",
"carimbo de data/hora": "2026-05-13T09:14:22Z",
"dados": {
"erro": {
"código": "obra_de_arte inacessível",
"mensagem": "GET on artwork_url falhou (timeout 30s) após 3 tentativas",
"repetível": verdadeiro,
"contexto": {
"url_da_obra": "https://cdn.yourbrand.com/art/drop-001.png"
}
}
}
}
# Valores comuns do código de erro:
# artwork_unreachable - o URL do seu trabalho artístico não respondeu
# artwork_invalid_format - não foi possível analisar o ficheiro (tentar PNG / PDF vetorial)
# artwork_resolution_low - DPI demasiado baixo para o produto selecionado
# address_invalid - o endereço do destinatário não foi validado
# fabric_unavailable - base de tecido fora de stock há >7 dias
# payment_method_failed - faturação em ficheiro recusada
# compliance_flag - encomenda assinalada por uma análise de conformidade
TESTE
Acionar eventos de amostra sem ordens reais.
POST /v1/webhooks/test
envia um evento sintético de qualquer tipo para o seu URL de webhook registado.
Útil para testar seu manipulador antes de fazer pedidos reais, ou para verificar
um novo endpoint após uma implantação.
Os webhooks da área restrita são enviados para o URL da área restrita. Use uma ferramenta de tunelamento (ngrok, Cloudflare Tunnel) para apontar os webhooks da sandbox para o localhost durante o desenvolvimento.
POST /v1/webhooks/test
enrolar -X POST $BASE_URL/v1/webhooks/test \ -H "Autorização: Portador $KEY" \ -H "Content-Type: application/json" \ -d '{ "evento": "order.dispatched", "sample_order_id": "amostra" }' # 200 OK { "delivery_id": "del_test_94kQ", "posted_to": "https://your-tunnel.ngrok.io/webhook", "estado": "em fila de espera" }
REGISTAR O SEU WEBHOOK
Defina o URL uma vez. Nós tratamos da entrega.
Um URL de webhook por conta, todos os tipos de eventos são disparados para ele. Filtro no
evento
no seu gestor. Configurar através do guia de integração.