Webhook per ordini e fatture in Italia

Name: Merch Italy
Address: IT

Sottoscrivi eventi order.*, invoice.* (via SdI) e shipment.*. Firmati HMAC-SHA256, retry 6×, replay-protected con X-Corp-Timestamp.

Inizia ora

Catalogo eventi

order.accepted, order.confirmed, order.in_production, order.shipped, order.delivered, order.cancelled, invoice.issued, invoice.paid, invoice.credit_note (tutti via SdI per IVA 22% in Italia), shipment.label_created, shipment.eta_changed, catalog.updated. Ogni evento include event_id, event_type, occurred_at, data{…}.

Firma e verifica

Header X-Corp-Signature: t=,v1=. Per verificare: signed_payload = t + '.' + raw_body; v1 = HMAC_SHA256(secret, signed_payload). Rifiuta se |now − t| > 5 minuti o firma non corrisponde. Tolleranza previene replay; includiamo anche X-Corp-Event-Id (UUID) — memorizza gli ultimi 10k ID e dedup.

Retry e dead-letter

Su risposta non-2xx: retry a 1m, 5m, 15m, 1h, 6h, 24h (sei tentativi su ~31 ore). Esaurito, sottoscrizione in pausa e alert email a ops registrato. Eventi dead-letter via GET /v1/webhooks/{id}/dead_letter per 30 giorni; replay manuale via POST /v1/webhooks/{id}/replay/{event_id}.

FAQ

Metodo HTTP e content-type?

POST application/json. Sempre UTF-8. Inviamo Content-Length e Content-Encoding: identity (no gzip di default).

Posso avere più endpoint?

Sì — fino a 10 sottoscrizioni attive per account, ognuna può filtrare per prefix event_type (es. invoice.*). Utile per separare traffico ERP e observability.

E se il mio endpoint è temporaneamente non disponibile?

I retry coprono ~31 ore; brevi outage assorbiti trasparentemente. Per outage più lunghi, replay degli eventi dead-letter quando torni online.

Gli eventi sono ordinati?

Eventi per la stessa risorsa (order_id) consegnati in ordine causale best-effort (no garanzia). Usa occurred_at + event_id per ricostruire l'ordine lato client se richiesto.

Come ruoto il signing secret?

POST /v1/webhooks/{id}/rotate_secret — restituisce il nuovo secret; quello vecchio resta valido 24 ore per grazia.