Skip to main content
Anteprima: non viene ancora inviato nulla. Qui è descritto il contratto dell’API di distribuzione (versione 1.0.0). Nessun avviso viene consegnato finché la sandbox non apre.
Un webhook è un avviso leggero: dice cosa è cambiato e lo nomina, e tu leggi la risorsa che nomina. Gli avvisi seguono Standard Webhooks, quindi una libreria per questo standard nel tuo linguaggio li può verificare.

Registra un endpoint

POST /webhooks (permesso manage:webhooks) registra un endpoint, e il tuo canale ne può avere al massimo cinque:
  • url è un indirizzo HTTPS pubblico sulla porta 443. Una destinazione privata, riservata, di loopback o link-local viene rifiutata (url_not_allowed), e i reindirizzamenti non vengono mai seguiti.
  • events elenca fino a 20 tipi di evento o pattern (*, property.*, availability.updated), ognuno coperto dai permessi della tua chiave.
  • La risposta contiene il secret di firma dell’endpoint (whsec_…), mostrato una volta sola: salvalo subito.
POST /webhooks/{webhook_id}/test invia un ping firmato e riporta l’esito. GET /webhooks/{webhook_id}/deliveries elenca le consegne fatte a un endpoint, dalla più recente, e GET /webhooks/{webhook_id}/deliveries/{delivery_id} ogni tentativo di una consegna; le consegne si conservano per 35 giorni.

Verifica la firma

Ogni avviso è un POST con tre intestazioni: Per verificarla:
  1. Rifiuta un timestamp che si discosta di più di 5 minuti dal tuo orologio, così un avviso intercettato non può essere rimandato più tardi.
  2. Calcola l’HMAC-SHA256 di id.timestamp.corpo sul corpo grezzo così come è arrivato, prima di qualsiasi parsing JSON. La chiave è la parte base64 del segreto dopo whsec_, decodificata.
  3. Accetta l’avviso se corrisponde almeno un valore v1,, confrontato in tempo costante. Durante la rotazione di un segreto arrivano due firme.

Applica un avviso

Il corpo è l’evento:
  • La consegna avviene almeno una volta, senza un ordine preciso. Scarta i duplicati in base a webhook-id.
  • Leggi la risorsa che l’evento nomina, e applicala solo quando la sua version è più alta di quella che hai.
  • Un evento availability.updated nomina una struttura e un intervallo di notti (from, to escluso) e non ha versione: rileggi sempre quell’intervallo.
  • Rispondi con un qualsiasi 2xx entro 10 secondi, e fai il lavoro dopo.

Nuovi tentativi e sospensione

Una risposta non 2xx o un timeout viene ritentato dopo 1 minuto, 5 minuti, 30 minuti, 2 ore e 6 ore, poi ogni 12 ore, ognuno con una variazione di ±20 %, per 3 giorni. Dopo, l’endpoint diventa inactive con suspended_reason: failing, e il tuo referente tecnico riceve un’e-mail. Una risposta 410 Gone lo rende inactive subito (gone). Un reindirizzamento non viene mai seguito e conta come non consegnato. A un endpoint inattivo non viene consegnato nulla. POST /webhooks/{webhook_id}/enable lo riattiva dopo che un ping firmato verso di esso va a buon fine. Non viene rimandato niente: recupera quello che si è perso da GET /events (Sincronizzazione).

Ruota un segreto

POST /webhooks/{webhook_id}/rotate-secret rilascia un nuovo segreto, mostrato una volta sola. Quello precedente continua a firmare accanto al nuovo per 24 ore (previous_secret_expires_at), quindi arrivano entrambe le firme e un verificatore che ha l’uno o l’altro segreto accetta l’avviso; invia "expire_immediately": true quando il segreto vecchio è finito in mani sbagliate. Cancellare un endpoint annulla le sue consegne in attesa e distrugge i suoi segreti.