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.eventselenca fino a 20 tipi di evento o pattern (*,property.*,availability.updated), ognuno coperto dai permessi della tua chiave.- La risposta contiene il
secretdi 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 è unPOST con tre intestazioni:
Per verificarla:
- Rifiuta un timestamp che si discosta di più di 5 minuti dal tuo orologio, così un avviso intercettato non può essere rimandato più tardi.
- Calcola l’HMAC-SHA256 di
id.timestamp.corposul corpo grezzo così come è arrivato, prima di qualsiasi parsing JSON. La chiave è la parte base64 del segreto dopowhsec_, decodificata. - 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.updatednomina una struttura e un intervallo di notti (from,toescluso) e non ha versione: rileggi sempre quell’intervallo. - Rispondi con un qualsiasi
2xxentro 10 secondi, e fai il lavoro dopo.
Nuovi tentativi e sospensione
Una risposta non2xx 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.