Înregistrează un endpoint
POST /webhooks (permisiunea manage:webhooks) înregistrează un endpoint, iar canalul tău poate avea cel mult cinci:
urleste o adresă HTTPS publică, pe portul 443. O țintă privată, rezervată, loopback sau link-local este refuzată (url_not_allowed), iar redirecționările nu sunt urmate niciodată.eventslistează cel mult 20 de tipuri de evenimente sau tipare (*,property.*,availability.updated), fiecare acoperit de permisiunile cheii tale.- Răspunsul conține
secret-ul de semnare al endpoint-ului (whsec_…), afișat o singură dată: păstrează-l acum.
POST /webhooks/{webhook_id}/test trimite un ping semnat și raportează rezultatul. GET /webhooks/{webhook_id}/deliveries listează livrările făcute către un endpoint, cele mai noi primele, iar GET /webhooks/{webhook_id}/deliveries/{delivery_id} fiecare încercare a uneia; livrările se păstrează 35 de zile.
Verifică semnătura
Fiecare notificare este unPOST cu trei anteturi:
Ca să o verifici:
- Respinge un timestamp care diferă cu mai mult de 5 minute de ceasul tău, ca o notificare interceptată să nu poată fi retrimisă mai târziu.
- Calculează HMAC-SHA256 peste
id.timestamp.corp, pe corpul brut exact cum a sosit, înainte de orice parsare JSON. Cheia este partea base64 a secretului de dupăwhsec_, decodată. - Acceptă notificarea dacă se potrivește oricare valoare
v1,, comparată în timp constant. Cât timp un secret este rotit, se trimit două semnături.
Aplică o notificare
Corpul este evenimentul:- Livrarea este cel puțin o dată, în nicio ordine anume. Elimină duplicatele după
webhook-id. - Citește resursa numită de eveniment și aplic-o doar când
version-ul ei este mai mare decât cel pe care îl ai. - Un eveniment
availability.updatednumește o proprietate și un interval de nopți (from,toexclusiv) și nu are versiune: citește întotdeauna din nou acel interval. - Răspunde cu orice
2xxîn cel mult 10 secunde și fă treaba după aceea.
Reîncercări și suspendare
Un răspuns non-2xx sau un timeout este reîncercat după 1 minut, 5 minute, 30 de minute, 2 ore și 6 ore, apoi la fiecare 12 ore, fiecare cu o variație de ±20 %, timp de 3 zile. După aceea endpoint-ul devine inactive cu suspended_reason: failing, iar contactul tău tehnic primește un e-mail. Un răspuns 410 Gone îl face inactive imediat (gone). O redirecționare nu este urmată niciodată și contează ca nelivrată.
La un endpoint inactiv nu se livrează nimic. POST /webhooks/{webhook_id}/enable îl reactivează după ce un ping semnat către el reușește. Nu se retrimite nimic: recuperează ce a ratat din GET /events (Sincronizare).
Rotește un secret
POST /webhooks/{webhook_id}/rotate-secret emite un secret nou, afișat o singură dată. Cel anterior continuă să semneze alături de el 24 de ore (previous_secret_expires_at), așa că sosesc ambele semnături și un verificator care deține oricare dintre secrete acceptă notificarea; trimite "expire_immediately": true când secretul vechi a ajuns unde nu trebuia. Ștergerea unui endpoint îi anulează livrările în așteptare și îi distruge secretele.