Webhooks para encomendas e faturas em Portugal
Subscreva eventos order.*, invoice.* (via Portal das Finanças (AT)) e shipment.*. Assinados HMAC-SHA256, retry 6×, protegidos contra replay com X-Corp-Timestamp.
Catálogo de eventos
order.accepted, order.confirmed, order.in_production, order.shipped, order.delivered, order.cancelled, invoice.issued, invoice.paid, invoice.credit_note (todos via Portal das Finanças (AT) para IVA 23% em Portugal), shipment.label_created, shipment.eta_changed, catalog.updated. Cada evento inclui event_id, event_type, occurred_at, data{…}.
Assinatura e verificação
Header X-Corp-Signature: t=
Retries e dead-letter
Em resposta não-2xx: retry a 1m, 5m, 15m, 1h, 6h, 24h (seis tentativas em ~31 horas). Esgotado, subscrição pausa e alerta email ao contacto registado. Eventos dead-letter via GET /v1/webhooks/{id}/dead_letter por 30 dias; replay manual via POST /v1/webhooks/{id}/replay/{event_id}.
FAQ
Que método HTTP e content-type?
POST application/json. Sempre UTF-8. Enviamos Content-Length e Content-Encoding: identity (sem gzip por defeito).
Posso ter múltiplos endpoints?
Sim — até 10 subscrições ativas por conta, cada uma pode filtrar por prefixo event_type (ex. invoice.*). Útil para separar tráfego ERP e observabilidade.
E se o meu endpoint estiver brevemente indisponível?
Os retries cobrem ~31 horas; outages breves absorvidos transparentemente. Para outages mais longos, replay de eventos dead-letter ao recuperar.
Os eventos são ordenados?
Eventos para o mesmo recurso (order_id) entregues em ordem causal best-effort (sem garantia). Use occurred_at + event_id para reconstruir ordem no cliente se necessário.
Como roto o secret de assinatura?
POST /v1/webhooks/{id}/rotate_secret — devolve o novo secret; o antigo continua válido 24 horas para período de graça.