Cada evento. Cada payload. Assinado.
A Fabrixa envia eventos de encomendas para o seu endpoint em tempo real. O seu servidor expõe um endpoint POST público; enviamos o corpo completo da encomenda com uma assinatura HMAC-SHA256 e o tópico do evento nos cabeçalhos. Verifique a assinatura, devolva rapidamente um 200 e processe de forma assíncrona.
Três cabeçalhos identificam e verificam o pedido.
Cada POST de webhook inclui os mesmos três cabeçalhos. Utilize x-webhook-topic para encaminhar o evento e x-webhook-signature para o verificar antes de confiar na entidade.
content-type é sempre application/json. x-webhook-signature é o HMAC-SHA256 codificado em base64 do corpo do pedido em formato bruto. x-webhook-topic é o nome do evento.
{
"content-type": "application/json",
"x-webhook-topic": "order.updated",
"x-webhook-signature": "YmEwNjBhMGMy...MAxMw=="
}
Dois tópicos, para já.
Cada webhook é acionado por um x-webhook-topic valor. Ambos contêm o objeto de encomenda completo, pelo que um único manipulador pode alternar no tópico.
Foi efetuada uma nova encomenda.
É acionado quando é criada uma encomenda no Fabrixa — quer através de um pedido da API, quer diretamente na plataforma.
Uma encomenda já existente é alterada.
É acionado quando os detalhes da encomenda se alteram — por exemplo, quando o estado da encomenda ou o estado do processamento da encomenda mudam para a fase seguinte.
O que os campos de estado podem indicar.
A payload transporta tanto uma encomenda status e um fulfillment_status. Ative estas opções para controlar o estado da sua encomenda.
- Completed — enviado ou levantado e receção confirmada.
- Canceled — o pagamento foi cancelado; a transação não foi concluída.
- On hold — a encomenda está temporariamente bloqueada.
- Imported — a encomenda foi importada para a plataforma.
- Unfulfilled — ainda não está preparado nem enviado.
- Partially fulfilled — alguns artigos já foram processados ou enviados, outros ainda estão pendentes.
- Scheduled — planeados e agendados para processamento.
- Rejected — o pedido de execução foi recusado.
- Fulfilled — totalmente processados e entregues ou disponibilizados.
Como é o corpo.
O texto completo order.updated payload, exatamente tal como documentado nos documentos de referência da API — a encomenda, os seus estados e as linhas com detalhes sobre a variante, o produto e a origem.
{
"id": 23069,
"number": "1250211835",
"comments": null,
"is_archived": false,
"status": "imported",
"fulfillment_status": "unfulfilled",
"purchased_at": "2025-04-17T16:17:21.000000Z",
"created_at": "2025-04-17T16:17:23.000000Z",
"updated_at": "2025-04-18T07:43:52.000000Z",
"rows": [
{
"id": 27954,
"quantity": 1,
"client_barcode": "1250211835",
"fulfillment_status": "unfulfilled",
"variant": {
"id": 293457,
"name": "Sherpa fleece deken",
"subtitle": "100x150",
"SKU": "SFD787231",
"product": {
"id": 5319, "name": "Sherpa fleece deken", "subtitle": "Sherpa fleece deken"
}
},
"sources": [
{
"type": "print",
"url": "https://storage.googleapis.com/fabrixa-api/…/120002795400.pdf",
"properties": { "fill_style": "contain" }
}
]
}
]
}
Recalcule o HMAC, compare e, em seguida, considere o corpo como fiável.
Recalcule o HMAC-SHA256 da payload bruta do pedido com a sua chave secreta, codifique-a em base64 e compare com x-webhook-signature. Utilize sempre uma comparação de tempo constante (hash_equals) para evitar ataques de temporização.
$payload = file_get_contents('php://input'); $secret = 'your-secret-key'; $expected = base64_encode( hash_hmac('sha256', $payload, $secret, true) ); $received = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? ''; // constant-time compare if (!hash_equals($expected, $received)) { http_response_code(403); exit('Invalid signature'); }
public function handle(Request $request)
{
$secret = 'your-secret-key';
$payload = $request->getContent();
$expected = base64_encode(
hash_hmac('sha256', $payload, $secret, true)
);
$received = $request->header('x-webhook-signature');
if (!hash_equals($expected, $received)) {
abort(403, 'Invalid signature');
}
// Continue processing…
}
Novas tentativas e a resposta que esperamos.
Até 10 tentativas; depois, é desativado
A 2xx (por exemplo, 200) ou um 301 / 302 é considerado um sucesso. Qualquer 4xx, 5xx ou se o tempo limite for atingido, é iniciada uma nova tentativa — até um total de 10. Após a décima falha, o webhook é desativado.
Devolver 200 rapidamente, processar de forma assíncrona
Confirme com 200 OK o mais rapidamente possível e, em seguida, processar a carga de trabalho de forma assíncrona através de uma tarefa em segundo plano ou de uma fila. Um ponto final lento pode ser considerado uma falha, mesmo que acabe por ser bem-sucedido.
Configure o seu endpoint de webhook.
O guia de integração explica passo a passo como registar o seu endpoint e como gerir o ciclo de vida da encomenda do início ao fim. A referência completa da API contém o esquema completo do payload.