Skip to main content
Preview: nimic nu este trimis încă. Pagina descrie contractul API-ului de distribuție (versiunea 1.0.0). Nicio notificare nu este livrată până nu se deschide sandbox-ul.
Un webhook este o notificare subțire: spune ce s-a schimbat și numește resursa, iar tu citești resursa numită. Notificările urmează Standard Webhooks, așa că o bibliotecă pentru acest standard în limbajul tău le poate verifica.

Înregistrează un endpoint

POST /webhooks (permisiunea manage:webhooks) înregistrează un endpoint, iar canalul tău poate avea cel mult cinci:
  • url este 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ă.
  • events listează 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 un POST cu trei anteturi: Ca să o verifici:
  1. 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.
  2. 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ă.
  3. 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.updated numește o proprietate și un interval de nopți (from, to exclusiv) ș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.