WEBHOOKS
Webhook
Ricevi eventi in tempo reale da Superroute — ordini, cambi di stato, aggiornamenti di tracciamento. Con payload firmati, tentativi automatici e debugger integrato.
WEBHOOKS
Ricevi eventi in tempo reale da Superroute — ordini, cambi di stato, aggiornamenti di tracciamento. Con payload firmati, tentativi automatici e debugger integrato.
Un webhook è una richiesta HTTP POST che Superroute invia a un URL configurato ogni volta che succede qualcosa — un ordine viene creato, una consegna completata, un evento di tracciamento registrato. Tu costruisci un endpoint di ricezione, noi vi consegnamo l'evento.
Gli eventi vengono accodati e inviati in modo asincrono. Ogni richiesta porta una firma HMAC-SHA256 per verificare la provenienza. Le consegne fallite (non 2xx o timeout) vengono riprovate con backoff esponenziale fino a 5 volte.
Configuri un segreto condiviso nella pagina impostazioni. Ogni webhook uscente viene firmato con tale segreto. Il ricevitore ricalcola la firma e confronta — se coincidono, il payload è autentico e non manomesso.
Sono disponibili otto tipi di eventi uscenti. Ognuno ha il proprio campo URL nella pagina impostazioni — puoi iscriverti a qualsiasi sottoinsieme.
Descrizione leggibile dalle macchine di tutti gli eventi in uscita, con schemi del payload, intestazioni e piani di ripetizione (AsyncAPI 3.0): asyncapi-webhooks.json
Si attiva alla creazione di un ordine di consegna locale (Delivery / Pickup / P2P) tramite qualsiasi canale: form web, API REST/GraphQL, sincronizzazione piattaforma e-commerce, regole automatiche, righe importate, ecc. Esclude gli ordini label-service e altri tipi non di consegna. Saltato nel flusso batch quando lo stesso destinatario ha anche order_create_async_postback_url configurato. Configura con order_create_webhook_url.
Esempi di PayloadSi attiva ad ogni transizione di stato — ritirato, in transito, consegnato, eccezione, annullato. Configura con order_status_change_webhook_url.
Esempi di PayloadSi attiva ad ogni evento del ciclo di vita di un pacco (informazioni inviate, inizio consegna, consegna riuscita, non consegnato, ecc.). Configura con tracking_event_webhook_url. Gli eventi di consegna e di ritiro contengono anche la prova di consegna: proof_files e proof_files_detail (file_id, type, url, full_url, URL di download firmato). Le foto caricate dopo l’evento arrivano come pod.files_updated. Ogni file include anche il contesto del suo evento: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) e service_status (1 = success / 2 = failed); per i file storici senza evento registrato sono null.
Esempi di PayloadSi attiva una volta al termine dell'elaborazione di un'importazione batch. Il payload contiene l'array dei risultati per riga. Configura con order_create_async_postback_url.
Esempi di PayloadAttivato quando una foto di consegna o una firma viene aggiunta, sostituita o rimossa (action: added / updated / removed) — un invio per file, niente più polling degli allegati. Si attiva configurando pod_files_webhook_url. Ogni file include anche il contesto del suo evento: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) e service_status (1 = success / 2 = failed); per i file storici senza evento registrato sono null. Quando il personale sostituisce una foto o una firma, o imposta una versione archiviata come attuale, il file viene inviato con action: updated e contiene solo l'immagine attuale; le versioni archiviate non vengono mai inviate.
Esempi di PayloadAttivato quando un ordine viene eliminato definitivamente, così il tuo sistema può replicare la rimozione. Si attiva configurando order_deleted_webhook_url.
Esempi di PayloadAttivato quando un tentativo di annullamento viene rifiutato (ad esempio l'ordine è già in consegna), così i tuoi processi operativi possono monitorare gli annullamenti falliti senza interrogare l'API. Si attiva configurando order_cancel_failed_webhook_url.
Esempi di PayloadSi attiva quando un posto della bacheca percorsi cambia titolare o la bacheca cambia stato — il campo action indica cosa è successo (claimed, standby, pooled, promoted, withdrawn, vetoed, replaced, assigned, awarded, lost, displaced, settled, board_opened, board_closed, board_cancelled). Solo a livello aziendale. Iscrizione tramite route_board_webhook_url.
Esempi di PayloadUn canale webhook separato per i fornitore di consegna terzi integrati con gli armadietti intelligenti. Gli eventi vengono consegnati all'endpoint configurato per il tuo account fornitore e ogni endpoint può sottoscrivere qualsiasi sottoinsieme di tipi di evento.
Sportelli Aperti — Si attiva nel momento in cui gli sportelli si aprono per un tentativo di consegna — sia che il corriere abbia usato lo schermo dell'armadietto con il codice di accesso sia l'API di apertura remota — incluse le riaperture per riassegnazione. Il blocco opening elenca ogni scomparto aperto con grid_id, numero sportello hardware compartment_number e pickup_locker_number (numero sequenziale di visualizzazione contato dall'alto verso il basso per colonna, poi da sinistra a destra). Ogni scomparto riporta anche pickup_locker_code: l'etichetta "{shelf_code}-{pickup_locker_number}" a cui viene indirizzato il destinatario; null quando lo scomparto non ha un numero di ritiro. Il payload include anche pickup_code: il codice di ritiro del destinatario, assegnato nel momento in cui si aprono gli sportelli; resta lo stesso codice dopo che il corriere conferma il deposito e diventa utilizzabile per il ritiro solo a deposito confermato.
Esempi di PayloadConsegnato nell'armadietto — Attivato quando un deposito è confermato e i pacchi sono nell'armadietto. Il payload include il codice di ritiro del destinatario. Ogni scomparto riporta anche pickup_locker_code: l'etichetta "{shelf_code}-{pickup_locker_number}" a cui viene indirizzato il destinatario; null quando lo scomparto non ha un numero di ritiro. Per gli sportelli aperti tramite l'API di apertura remota la piattaforma liquida il deposito non appena l'armadietto segnala chiusi tutti gli sportelli aperti, quindi l'evento scatta senza una chiamata confirm; confirmed_by indica il percorso di liquidazione: courier_terminal, partner_api, door_close, timeout_door_closed o console.
Esempi di PayloadRitirato — Attivato quando il destinatario ha ritirato i pacchi depositati.
Esempi di PayloadConsegna non riuscita — Attivato quando una consegna fallisce; sono inclusi i codici di errore per pacco.
Esempi di PayloadScaduto — Attivato quando un codice di consegna inutilizzato o un deposito non ritirato supera la scadenza.
Esempi di PayloadAnnullato — Attivato quando una consegna viene annullata prima del completamento.
Esempi di PayloadRiapertura di correzione — Attivato quando gli scomparti occupati vengono riaperti entro la finestra di correzione per rimediare a un posizionamento errato — dallo schermo dell'armadietto o tramite API. Il blocco correction elenca gli scomparti riaperti. Ogni scomparto riporta anche pickup_locker_code: l'etichetta "{shelf_code}-{pickup_locker_number}" a cui viene indirizzato il destinatario; null quando lo scomparto non ha un numero di ritiro.
Esempi di PayloadCodice di ritiro modificato — Si attiva quando il partner rigenera il codice di consegna o il codice di ritiro di una consegna. Il blocco rotation indica quale codice è stato sostituito, quando, e se la notifica al destinatario è stata reinviata — il nuovo codice non viaggia mai in un webhook; viene rivelato solo nella risposta diretta dell'API di rigenerazione.
Esempi di PayloadPacco corriere distribuito — Scatta quando un pacco preavvisato del corriere ricevuto in un magazzino viene messo su un ordine di distribuzione verso la sede indicata dal corriere. Il blocco data porta il numero di pacco, il riferimento del corriere e il numero socio, l'ordine di distribuzione (order_id, order_ref, status) e le sedi di origine e destinazione. Registrato solo per i corrieri con account fornitore.
Esempi di PayloadPacco corriere caricato — Scatta quando il pacco viene scansionato sul camion nel magazzino di origine; distribution.status è in_transit e loaded_at è valorizzato.
Esempi di PayloadPacco corriere consegnato alla sede — Scatta quando l'autista consegna l'ordine di distribuzione in sede; distribution.status è delivered e delivered_at è valorizzato. La riposizione è un evento successivo e separato.
Esempi di PayloadPacco corriere riposto alla sede — Scatta quando il pacco viene riposto in sede, in uno scomparto di armadietto o su uno scaffale; location porta grid_id, grid_code e shelf_code. La notifica di ritiro al destinatario parte in quel momento.
Esempi di PayloadPacco corriere rimosso dalla distribuzione — Scatta quando il pacco viene tolto da un ordine di distribuzione prima della partenza, o l'ordine viene annullato; distribution.reason è removed o cancelled. Il pacco torna nell'elenco di distribuzione del magazzino.
Esempi di PayloadFirma e Verifica: I webhook degli armadietti fornitore usano un proprio schema di firma: X-Webhook-Signature è base64(HMAC-SHA256(segreto, timestamp + "\n" + id consegna + "\n" + corpo grezzo)), dove timestamp e id consegna provengono dagli header X-Webhook-Timestamp e X-Webhook-Delivery-Id. Verifica anche X-Webhook-Content-Digest (SHA-256 del corpo) e rifiuta i timestamp obsoleti. X-Webhook-Id resta stabile tra i tentativi — usalo per l'idempotenza.
Come Configurare: Gli endpoint si gestiscono in Consegna di terzi → Armadietto fornitore → Impostazioni, un endpoint per fornitore, con un elenco di eventi selezionabile. Le consegne fallite vengono ritentate con backoff esponenziale fino a 7 volte prima della dead letter; gli eventi in dead letter possono essere reinviati manualmente dalla pagina eventi.
Eventi sandbox (armadietti simulati): Le consegne create su armadietti simulati emettono gli stessi eventi webhook della produzione, firmati con lo stesso segreto, così da poter sviluppare con traffico realistico. Gli eventi sandbox sono contrassegnati in tre modi: il payload contiene "livemode": false, l'event_id inizia con PLE-MOCK- e la richiesta include l'header X-Webhook-Test: 1. Se sull'endpoint è configurato un URL sandbox, gli eventi sandbox vengono inviati lì invece che all'URL di produzione; altrimenti ripiegano sull'URL di produzione, sempre contrassegnati. L'interruttore «Consegna eventi sandbox» ferma completamente la consegna sandbox.
Webhook di consegna pacchi inviati ai fornitori di consegna di terzi (corrieri). Coprono il ciclo di vita delle assegnazioni di consegna, così il corriere non deve più interrogare la piattaforma in cerca di nuovi incarichi. Questa categoria è separata dagli eventi degli armadietti intelligenti qui sotto: ogni fornitore configura per categoria un endpoint, un segreto di firma e una sottoscrizione eventi indipendenti — nel proprio portale fornitore oppure tramite l'operatore della piattaforma.
Assegnazione creata — Si attiva quando un ordine viene assegnato al fornitore — da una regola automatica o manualmente. Il payload contiene il numero di assegnazione, gli identificativi dell'ordine e i numeri di tracciamento dei pacchi.
Esempi di PayloadPacchi affidati — Si attiva quando il magazzino ha consegnato fisicamente al fornitore tutti i pacchi dell'assegnazione.
Esempi di PayloadAssegnazione annullata — Si attiva quando la piattaforma ritira un'assegnazione dal fornitore. Il campo reason distingue cancelled (l'assegnazione è stata annullata presso il vettore), fallback_to_self_delivery (la piattaforma ha ripreso l'ordine in consegna propria) e reassigned (l'ordine è stato spostato a un altro fornitore).
Esempi di PayloadConsegna parziale — Si attiva quando una parte della spedizione è stata consegnata mentre altri colli sono ancora in corso. L'array packages riporta l'esito di ogni collo e legs elenca gli ordini esterni prenotati presso il corriere: uno per collo quando il corriere non accetta spedizioni multicollo.
Esempi di PayloadFirma e Verifica: I webhook di consegna di terzi usano lo stesso schema di firma dei webhook degli armadietti fornitore: X-Webhook-Signature è base64(HMAC-SHA256(secret, timestamp + "\n" + delivery id + "\n" + raw body)), dove timestamp e delivery id provengono dagli header X-Webhook-Timestamp e X-Webhook-Delivery-Id. Verifica anche X-Webhook-Content-Digest (SHA-256 del corpo) e rifiuta i timestamp obsoleti. X-Webhook-Id resta stabile tra i tentativi — usalo per l'idempotenza.
Come Configurare: I fornitori configurano questo endpoint autonomamente nel portale fornitore (Impostazioni webhook), oppure lo fa l'operatore della piattaforma in Consegna di terzi → Fornitori → Webhook. Un endpoint per fornitore con un elenco di eventi selezionabile. Il segreto di firma può essere generato automaticamente o impostato con un valore personalizzato, ed è consultabile nella pagina delle impostazioni. Le consegne fallite vengono ritentate con backoff esponenziale fino a 7 volte prima della dead letter; gli eventi in dead letter possono essere reinviati manualmente. Dalla pagina delle impostazioni è possibile inviare in qualsiasi momento un evento di test (mock) firmato: le richieste di test portano l'header X-Webhook-Test: 1 e contengono "test": true nei dati del payload.
Push firmati sulle consegne scambiate tramite l'Open Order Handoff Protocol: cambi di ciclo di vita (accettata, rifiutata, scaduta, annullata), risposte alle modifiche, eventi di tracciamento e nuove righe di liquidazione. Sottoscritto per token OHP via POST /api/v1/ohp/subscriptions; l'endpoint deve restituire una challenge prima che la sottoscrizione esista. Ogni payload è la busta OHP; message_id resta identico a ogni tentativo — deduplicare su di esso. Il pull resta la fonte di verità.
Firma e Verifica: X-Ohp-Signature: v1= + HMAC-SHA256 esadecimale di "{timestamp}.{raw body}" con il segreto della sottoscrizione. X-Ohp-Timestamp cambia per tentativo; X-Ohp-Delivery è uguale a message_id. CloudEvents e Standard Webhooks sono disponibili per sottoscrizione.
Come Configurare: Gestito con il token OHP: POST /api/v1/ohp/subscriptions (url, secret, events, format, signature), GET per elencare, DELETE per revocare. Il catalogo leggibile dalle macchine elenca ogni evento sotto il mittente ohp.
Eventi granulari e opzionali accanto al classico webhook order.status_change (che resta invariato): chi è stato assegnato, se l'autista ha accettato, quando il pacco è stato ritirato, è in viaggio, consegnato o fallito, oltre ai cambi di turno degli autisti e alle posizioni degli autisti a frequenza limitata. Non viene inviato nulla finché non configuri gli URL qui sotto.
Un autista è stato assegnato all'ordine (manualmente, dalla pianificazione dei giri o dall'assegnazione automatica). data.source = auto_assign quando lo ha fatto l'orchestratore.
Esempi di PayloadL'ordine ha perso il suo autista (passaggio di consegne, revoca, rifiuto, timeout). data.previous_driver_id indica chi lo aveva.
Esempi di PayloadL'autista ha accettato nell'app un ordine assegnato automaticamente (turno autisti con accettazione obbligatoria).
Esempi di PayloadL'autista ha rifiutato un ordine assegnato; data.reason contiene il motivo opzionale in testo libero.
Esempi di PayloadL'autista ha avviato il ritiro (stato Ritiro iniziato / In Ritiro).
Esempi di PayloadIl pacco è stato ritirato (stato Già ritirato).
Esempi di PayloadIl pacco è in viaggio verso il destinatario (stato Consegna iniziata / In Consegna).
Esempi di PayloadLa consegna è riuscita (stato Riuscito).
Esempi di PayloadIl tentativo di consegna è fallito (Riconsegnare più tardi, Da riprogrammare, Rifiutato dal destinatario).
Esempi di PayloadL'ordine è stato annullato.
Esempi di PayloadLo staff (o un autista, se consentito) ha contrassegnato l'ordine come pronto per il ritiro (Opzioni di dispatch → pronto per il ritiro).
Esempi di PayloadUn autista è entrato o uscito dal turno nell'app (opzione turno autisti).
Esempi di PayloadUna posizione dell'autista proveniente dall'app o dal tracker, limitata per autista da driver_location_min_interval_sec (predefinito 60 s). Inviata solo a driver_location_webhook_url.
Esempi di PayloadCome Configurare: Impostazioni → Webhook (oppure GET/PUT /api/v1/webhook-settings, GraphQL webhookSettingsUpdate): order_lifecycle_webhook_url riceve tutti gli eventi order.* e driver.on_duty_changed; order_lifecycle_events li restringe a un elenco separato da virgole; driver_location_webhook_url e driver_location_min_interval_sec controllano driver.location_update. È possibile indicare più URL separati da virgole. Le consegne compaiono nel registro delle consegne webhook con reference_type order / driver.
Firma e Verifica: Firmato esattamente come ogni altro webhook in uscita del tuo account: header Signature legacy più X-Webhook-Id / X-Webhook-Timestamp / X-Webhook-Signature-V2 con il tuo webhook_sign_secret. I nuovi tentativi riutilizzano lo stesso event_id: usalo per la deduplicazione.
Eventi facoltativi per i pacchi gestiti dai tuoi armadietti intelligenti, chioschi e smart drop: un pacco depositato in una macchina, ritirato, prelevato dal personale o oltre la scadenza di ritiro, e i problemi aperti o risolti su di esso. Solo aggiuntivo: nessun webhook esistente cambia e non viene inviato nulla finché non configuri device_order_webhook_url.
Un pacco è stato depositato nella macchina e attende la persona successiva (destinatario, corriere o operatore, vedi data.device_order.next_actor). due_at è la scadenza di ritiro.
Esempi di PayloadIl pacco è stato ritirato dalla persona che attendeva: il destinatario, il corriere o il personale che svuota uno smart drop.
Esempi di PayloadIl personale ha prelevato il pacco dalla macchina. removal_reason indica il motivo: overdue_return, handover, relay, anomaly o recovery.
Esempi di PayloadIl pacco ha superato il suo due_at senza essere ritirato. È ancora nella macchina e il codice funziona ancora; overdue_at viene impostato e next_actor diventa operator.
Esempi di PayloadÈ stato aperto un problema sulla gestione (ad esempio door_left_open, deposit_unverified, item_missing, overdue). data.exception contiene id, type, severity e status.
Esempi di PayloadUna persona ha chiuso un problema sulla gestione. data.exception.status è resolved o dismissed e resolution_action indica cosa è stato fatto.
Esempi di PayloadEsempi di Payload: data.device_order: id, kind, status, next_actor, device_type, device_id, device_name, grid_code, reference_number, order_id, external_order_id, due_at, overdue_at, stored_at, ended_at, removal_reason (orari in ISO 8601, null finché non raggiunti). Gli eventi di problema aggiungono data.exception: id, type, severity, status, resolution_action. Il codice di ritiro non è mai incluso. event_id è DOE-<id dell'evento del registro> e resta invariato nei tentativi successivi.
Come Configurare: Impostazioni → Webhooks (o GET/PUT /api/v1/webhook-settings): device_order_webhook_url riceve ogni evento device_order.*; device_order_events lo limita a un elenco separato da virgole. Più URL possono essere separati da virgole. Le consegne compaiono nel registro delle consegne webhook con reference_type device_order.
Firma e Verifica: Firmato esattamente come ogni altro webhook in uscita del tuo account: header Signature legacy più X-Webhook-Id / X-Webhook-Timestamp / X-Webhook-Signature-V2 con il tuo webhook_sign_secret. I nuovi tentativi riutilizzano lo stesso event_id: usalo per la deduplicazione.
I pacchi che un vettore partner consegna nei tuoi armadietti con il proprio account non vengono inviati su questo canale; il partner li riceve tramite i webhook degli armadietti del fornitore.
Puoi configurare i webhook a due livelli: aziendale (copre tutto) o per cliente (sovrascrive per quel sotto-account B2B specifico).
Accedi e vai in Impostazioni → API e Webhook. Le sovrascritture per cliente sono nella pagina di dettaglio del cliente.
Scegli una stringa di almeno 16 caratteri, idealmente 32+ byte casuali. Il ricevitore la userà per verificare le firme.
Compila solo gli URL degli eventi che ti interessano. Lascia gli altri vuoti.
webhook_sign_secretConfiguri un segreto condiviso nella pagina impostazioni. Ogni webhook uscente viene firmato con tale segreto. Il ricevitore ricalcola la firma e confronta — se coincidono, il payload è autentico e non manomesso.order_create_webhook_urlSi attiva alla creazione di un ordine di consegna locale (Delivery / Pickup / P2P) tramite qualsiasi canale: form web, API REST/GraphQL, sincronizzazione piattaforma e-commerce, regole automatiche, righe importate, ecc. Esclude gli ordini label-service e altri tipi non di consegna. Saltato nel flusso batch quando lo stesso destinatario ha anche order_create_async_postback_url configurato. Configura con order_create_webhook_url.order_status_change_webhook_urlSi attiva ad ogni transizione di stato — ritirato, in transito, consegnato, eccezione, annullato. Configura con order_status_change_webhook_url.tracking_event_webhook_urlSi attiva ad ogni evento del ciclo di vita di un pacco (informazioni inviate, inizio consegna, consegna riuscita, non consegnato, ecc.). Configura con tracking_event_webhook_url. Gli eventi di consegna e di ritiro contengono anche la prova di consegna: proof_files e proof_files_detail (file_id, type, url, full_url, URL di download firmato). Le foto caricate dopo l’evento arrivano come pod.files_updated. Ogni file include anche il contesto del suo evento: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) e service_status (1 = success / 2 = failed); per i file storici senza evento registrato sono null.order_create_async_postback_urlSi attiva una volta al termine dell'elaborazione di un'importazione batch. Il payload contiene l'array dei risultati per riga. Configura con order_create_async_postback_url.pod_files_webhook_urlAttivato quando una foto di consegna o una firma viene aggiunta, sostituita o rimossa (action: added / updated / removed) — un invio per file, niente più polling degli allegati. Si attiva configurando pod_files_webhook_url. Ogni file include anche il contesto del suo evento: tracking_event_id, tracking_event_status_id, tracking_event_key, service_type (1 = delivery / 2 = pickup) e service_status (1 = success / 2 = failed); per i file storici senza evento registrato sono null. Quando il personale sostituisce una foto o una firma, o imposta una versione archiviata come attuale, il file viene inviato con action: updated e contiene solo l'immagine attuale; le versioni archiviate non vengono mai inviate.order_deleted_webhook_urlAttivato quando un ordine viene eliminato definitivamente, così il tuo sistema può replicare la rimozione. Si attiva configurando order_deleted_webhook_url.order_cancel_failed_webhook_urlAttivato quando un tentativo di annullamento viene rifiutato (ad esempio l'ordine è già in consegna), così i tuoi processi operativi possono monitorare gli annullamenti falliti senza interrogare l'API. Si attiva configurando order_cancel_failed_webhook_url.route_board_webhook_urlSi attiva quando un posto della bacheca percorsi cambia titolare o la bacheca cambia stato — il campo action indica cosa è successo (claimed, standby, pooled, promoted, withdrawn, vetoed, replaced, assigned, awarded, lost, displaced, settled, board_opened, board_closed, board_cancelled). Solo a livello aziendale. Iscrizione tramite route_board_webhook_url.device_order_webhook_urlEventi facoltativi per i pacchi gestiti dai tuoi armadietti intelligenti, chioschi e smart drop: un pacco depositato in una macchina, ritirato, prelevato dal personale o oltre la scadenza di ritiro, e i problemi aperti o risolti su di esso. Solo aggiuntivo: nessun webhook esistente cambia e non viene inviato nulla finché non configuri device_order_webhook_url.Tutte le novità di API e webhook — annullamento idempotente, feed di riconciliazione, firme v2, nuovi eventi — con esempi pronti da copiare. Tutto pienamente retrocompatibile.
Ogni webhook uscente porta una firma HMAC-SHA256 codificata in esadecimale nell'header. Il ricevitore deve ricalcolarla sul body grezzo con il segreto condiviso e rifiutare la richiesta se non corrisponde.
Ogni URL webhook può ricevere gli eventi nel formato nativo o come CloudEvents, e può anche ricevere le intestazioni di firma Standard Webhooks. Si imposta per URL nelle impostazioni webhook. Un URL senza impostazione riceve gli eventi esattamente come prima.
native — Il corpo JSON e le intestazioni descritti in questa pagina.ce_binary — Lo stesso corpo; gli attributi CloudEvents sono inviati come intestazioni ce-*.ce_structured — Il corpo è un CloudEvent (Content-Type: application/cloudevents+json) con il corpo nativo in data. È identico a ogni ritentativo e le firme native lo coprono.ce-id e webhook-id contengono l’event_id proprio dell’evento quando il corpo ne ha uno, altrimenti X-Webhook-Event-Id. X-Webhook-Event-Id non cambia. ce-source e ce-srbusiness indicano l’azienda, anche per gli invii ai suoi clienti.
I webhook delle consegne negli armadietti dei partner e della consegna di terzi offrono la stessa scelta per endpoint, nella pagina delle impostazioni webhook del fornitore. Le callback dei piani di carico e di Open Platform la ricevono per richiesta: callback_format e callback_signature, oppure callback.format e callback.signature. Per questi, ce-id e webhook-id sono l’identificativo proprio dell’evento (X-Webhook-Id, X-Webhook-Event-Id o X-Open-Delivery), ce-source indica l’azienda mittente e per 24 ore dopo una rotazione della chiave del fornitore webhook-signature contiene una firma per chiave.
I webhook dei dataset offrono la stessa scelta per webhook, nel modulo del webhook e nella sua API (event_format e standard_signature). Standard Webhooks usa la chiave segreta del webhook, quindi ne richiede una. Gli URL dei webhook dei dataset devono essere indirizzi HTTPS pubblici.
Con Standard Webhooks ogni invio include anche webhook-id, webhook-timestamp e webhook-signature. Sono firmati di nuovo a ogni ritentativo, quindi un ritentativo rientra in una tolleranza di 5 minuti. La chiave è la tua chiave di firma webhook in formato whsec_, mostrata nella pagina delle impostazioni. Le intestazioni native continuano a essere inviate.
Ogni mittente firma in modo diverso. Il nome di intestazione X-Webhook-Signature è usato da tre mittenti con tre metodi diversi; verifica con il metodo del mittente che ti ha chiamato.
| Mittente | Intestazioni | Firma |
|---|---|---|
| Webhook del tenant (questa pagina) | Content-Type, Signature, X-Webhook-Event-Id, X-Webhook-Timestamp, X-Webhook-Signature-V2 |
Signature = hex(HMAC-SHA256(body))
X-Webhook-Signature-V2 = hex(HMAC-SHA256(timestamp + "." + body)) |
| Consegne negli armadietti dei partner | Content-Type, X-Webhook-Id, X-Webhook-Delivery-Id, X-Webhook-Timestamp, X-Webhook-Key-Id, X-Webhook-Content-Digest, X-Webhook-Signature, X-Webhook-Test |
X-Webhook-Signature = "v1=" + base64(HMAC-SHA256(timestamp + "\n" + delivery_id + "\n" + body)) |
| Assegnazioni a consegna di terzi | Content-Type, X-Webhook-Id, X-Webhook-Delivery-Id, X-Webhook-Timestamp, X-Webhook-Key-Id, X-Webhook-Content-Digest, X-Webhook-Signature |
X-Webhook-Signature = "v1=" + base64(HMAC-SHA256(timestamp + "\n" + delivery_id + "\n" + body)) |
| Callback dei piani di carico | Content-Type, X-Webhook-Event-Id, X-Webhook-Event-Type, X-Webhook-Timestamp, X-Webhook-Signature |
X-Webhook-Signature = "v1=" + hex(HMAC-SHA256(timestamp + "." + body)) |
| Callback dei job di Open Platform | Content-Type, X-Open-Event, X-Open-Delivery, X-Open-Job, X-Open-Timestamp, X-Open-Signature |
X-Open-Signature = "v1=" + hex(HMAC-SHA256(timestamp + "." + body)) |
| OHP push | Content-Type, X-Ohp-Event, X-Ohp-Delivery, X-Ohp-Timestamp, X-Ohp-Signature |
|
| Webhook dei dataset | Content-Type, X-Webhook-Event, X-Webhook-Timestamp, X-Webhook-Signature |
X-Webhook-Signature = hex(HMAC-SHA256(body)) |
| Webhook del tenant con Standard Webhooks | webhook-id, webhook-timestamp, webhook-signature |
webhook-signature = "v1," + base64(HMAC-SHA256(webhook-id + "." + webhook-timestamp + "." + body)) |
Il tuo fornitore di servizi può nascondere i propri prezzi a un account cliente, per famiglia di ordine (Consegna Locale, Servizio Etichette, Servizio di Spedizione, Servizio LTL, Servizi di Stoccaggio, Servizi di trasloco, ordini dispositivo). Quando ciò ti riguarda, le consegne al tuo endpoint non contengono campi di prezzo: shipping_price, price_details, currency, tasse, importi dei supplementi, prezzi delle tariffe e simili vengono omessi anziché inviati come zero. Gli elenchi di tariffe conservano rate_id e i nomi dei servizi per poterne ancora scegliere uno.
L'endpoint dovrebbe rispondere rapidamente con 2xx. Altrimenti, in caso di timeout o irraggiungibilità, la consegna viene riprovata.
Incolla un payload ricevuto, il valore dell'header Signature e il tuo segreto — lo strumento ricalcola la firma nel browser (nulla esce da questa pagina) e ti dice se coincide.
Spara un webhook reale e firmato correttamente dal nostro server a un URL che fornisci. Usalo per verificare raggiungibilità del ricevitore, parsing del payload e logica di verifica firma.
Vedi i tentativi di consegna webhook più recenti del tuo account — eventi reali di produzione e test inviati da questa pagina. Incolla il Bearer token per caricare.
I registri di consegna vengono conservati per 90 giorni.
Un reinvio manuale riceve un nuovo X-Webhook-Event-Id. Un event_id portato dall’evento stesso (pod.files_updated, order.deleted, eventi del ciclo di vita e degli ordini dispositivo) mantiene il valore originale.
| Tempo | Evento | URL | Stato | HTTP | Tentativo | Tempo (ms) | Prova? | Azioni |
|---|---|---|---|---|---|---|---|---|
| Nessuna consegna webhook trovata. | ||||||||