Webhook e recupero degli eventi

Passaggio 1 — Configura una destinazione

Un amministratore espande una chiave API in API e integrazioni e aggiunge una destinazione HTTP o HTTPS. HTTPS è raccomandato; l’interfaccia segnala HTTP, indirizzi IP diretti e indirizzi locali senza impedirne la registrazione. Il middleware deve poter raggiungere l’URL affinché la consegna funzioni. La destinazione appartiene alla chiave e possiede un proprio segreto di firma, mostrato solo alla creazione o alla rotazione. Seleziona i tipi di evento se il ricevitore necessita soltanto di una parte del flusso. Ruotare o revocare la chiave influisce anche sulle destinazioni: prepara il ricevitore prima di attivare la consegna.

“Ricevitore pronto” significa che destinazione e segreto sono configurati, non che un evento sia già arrivato. Mantieni separati nei log e nel monitoraggio i comandi API in uscita, le consegne webhook in ingresso e il recupero con GET /v1/events. Un PUT o POST avviato dal tuo backend non è un webhook ricevuto.

Per confermare l’associazione, confronta l’URL esatto mostrato per la chiave con quello esposto dal ricevitore e salva il segreto restituito per quella destinazione. L’API non lo mostra una seconda volta. Considera ricevuta una consegna live soltanto dopo che un POST in ingresso ha superato la verifica della firma; possedere il segreto dimostra la configurazione, non la consegna.

Passaggio 2 — Verifica prima di elaborare

Ogni consegna contiene webhook-id, webhook-timestamp e webhook-signature. La firma segue Standard Webhooks: HMAC-SHA256 sui byte UTF-8 di webhook-id + "." + webhook-timestamp + ".", seguiti dai byte esatti del corpo grezzo. Il segreto inizia con whsec_ e contiene una chiave di firma codificata Base64. Confronta la firma Base64 di una voce v1, in tempo costante.

Rifiuta timestamp distanti più di cinque minuti dall’ora del server. Verifica la firma prima di interpretare il JSON. Controlla che l’id dell’evento coincida con webhook-id, quindi registra quell’ID prima di applicare effetti di business. Una rapida risposta 2xx conferma la consegna.

Le consegne sono at least once e possono arrivare fuori ordine. Deduplica tramite ID evento. Un evento di completamento contiene identificativi e percorsi API: recupera report o dossier correnti tramite l’API autenticata quando servono i dati completi. Gli eventi principali sono rental.departure.completed e rental.return.completed; correzioni e disponibilità PDF hanno eventi distinti. Consulta la definizione OpenAPI Rental per tutti i tipi e i campi.

Passaggio 3 — Riconcilia dopo ogni segnale

Dopo un webhook di completamento valido, rileggi il dossier Rental o l’indice dei report tramite l’API autenticata. Il JSON può essere disponibile prima del PDF; segui il flusso 200/202 descritto in Report e prove. Non bloccare indefinitamente il processo aspettando un webhook: la riconciliazione periodica resta valida anche con un ricevitore sano.

Passaggio 4 — Recupera gli eventi persi

Usa GET /v1/events con il cursore e l’eventuale filtro created_after dopo un’interruzione. Gli eventi sono disponibili per 30 giorni. Avanza il cursore memorizzato soltanto dopo aver elaborato la pagina restituita. Se il ricevitore non era disponibile, la piattaforma ritenta le consegne fallite fino a otto volte nell’arco di 48 ore; un amministratore può consultare e ritentare gli errori recenti da API e integrazioni.

Considera il feed degli eventi una notifica e le route autenticate delle risorse la fonte dei dati correnti. Identità e versioni dei report spiega come archiviare i risultati in modo sicuro.

Se non arriva alcun evento firmato

1. Verifica che la destinazione appartenga alla stessa chiave e allo stesso ambiente usati per le chiamate API.
2. Verifica che rental.departure.completed e rental.return.completed siano selezionati e che l’URL sia ancora esatto.
3. Consulta la cronologia delle consegne. Un codice non 2xx, un timeout o una firma rifiutata indica un errore del ricevitore; una chiave disabilitata o revocata va corretta prima del nuovo tentativo.
4. Esegui subito GET /v1/events per proseguire l’elaborazione mentre ripari la consegna.
5. Ruota il segreto solo se il ricevitore non possiede più il valore corrispondente; aggiornalo prima di ritentare.

Per l’escalation comunica l’ID dell’evento o della consegna e il request_id della risposta API; non comunicare mai il segreto di firma.