Webhook
Iscriviti alle modifiche invece di interrogarle di continuo. Un webhook non costa nulla sulla tua quota di richieste, il che lo rende molto più economico che rileggere un mercato a intervalli regolari.
/v1/api/webhookswebhooks:manageElencare i webhook
Tutti gli endpoint registrati dalla tua organizzazione.
Il segreto di firma non viene mai incluso. Viene mostrato una sola volta alla creazione dell'endpoint, e un elenco che lo restituisse lo consegnerebbe a chiunque possa leggere questa chiamata.
Risposta
{
"data": [
{
"id": "whk_1b7e6c19a139404cb173d23fcb3331c4",
"url": "https://example.com/hooks/skautik",
"events": ["property.created", "property.withdrawn"],
"active": true,
"created_at": "2026-08-13T10:43:37Z",
"updated_at": "2026-08-13T10:43:37Z"
}
]
}https://api.skautik.com/v1/api/webhooks
GET /v1/api/webhooks HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…/v1/api/webhooks/eventswebhooks:manageElencare gli eventi disponibili
Gli eventi a cui un endpoint può iscriversi, con il significato di ciascuno.
Servito dallo stesso elenco su cui l'API effettua la validazione, quindi non può restare indietro rispetto a ciò che è realmente recapitabile.
Risposta
{
"data": [
{
"name": "property.created",
"description": "A property was added to your organisation."
}
]
}https://api.skautik.com/v1/api/webhooks/events
GET /v1/api/webhooks/events HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…/v1/api/webhookswebhooks:manageCreare un webhook
Registra un endpoint HTTPS per un insieme di eventi.
La risposta contiene un segreto di firma, mostrato una sola volta. Conservalo subito: ogni consegna è firmata con esso, e un gestore che non verifica la firma accetterà chiamate contraffatte da chiunque scopra l'URL.
Campi del corpo
| Nome | Tipo | Descrizione |
|---|---|---|
urlobbligatorio | string | Endpoint HTTPS. L'HTTP in chiaro viene rifiutato. esempio: https://example.com/hooks/skautik |
eventsobbligatorio | array | Nomi degli eventi a cui iscriversi. Ogni nome deve essere uno di quelli elencati sopra; un nome non riconosciuto viene rifiutato invece di non scattare mai in silenzio. esempio: ["property.created", "inquiry.created"] |
Corpo della richiesta
{
"url": "https://example.com/hooks/skautik",
"events": ["property.created", "property.withdrawn"]
}Risposta
{
"data": {
"webhook": {
"id": "whk_1b7e6c19a139404cb173d23fcb3331c4",
"url": "https://example.com/hooks/skautik",
"events": ["property.created", "property.withdrawn"],
"active": true,
"created_at": "2026-08-13T10:43:37Z",
"updated_at": "2026-08-13T10:43:37Z"
},
"secret": "whsec_uEw7ugUA3saVyNo087Sg3XvhBnWI0txICtik-ySKD2k"
}
}Risposte degne di nota
- 201
- Creato. signing_secret compare soltanto in questa risposta.
- 422
- L'URL non è HTTPS, non è raggiungibile, oppure un nome di evento è sconosciuto.
https://api.skautik.com/v1/api/webhooks
POST /v1/api/webhooks HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…
Content-Type: application/json
{
"url": "https://example.com/hooks/skautik",
"events": ["property.created", "property.withdrawn"]
}/v1/api/webhooks/{webhook_id}webhooks:manageRecuperare un webhook
Un endpoint con lo stato di salute delle consegne recenti.
Parametri di percorso
| Nome | Tipo | Descrizione |
|---|---|---|
webhook_idobbligatorio | string | Identificatore del webhook. esempio: whk_1b7e6c19a139404cb173d23fcb3331c4 |
https://api.skautik.com/v1/api/webhooks/{webhook_id}
GET /v1/api/webhooks/whk_1b7e6c19a139404cb173d23fcb3331c4 HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…/v1/api/webhooks/{webhook_id}webhooks:manageAggiornare un webhook
Modifica l'URL, gli eventi o se è attivo.
È un aggiornamento parziale: ciò che ometti resta com'è. Impostare active su false ferma le consegne senza perdere la registrazione, ed è ciò a cui ricorrere mentre sistemi un gestore.
Parametri di percorso
| Nome | Tipo | Descrizione |
|---|---|---|
webhook_idobbligatorio | string | Identificatore del webhook. esempio: whk_1b7e6c19a139404cb173d23fcb3331c4 |
Campi del corpo
| Nome | Tipo | Descrizione |
|---|---|---|
url | string | Nuovo endpoint HTTPS. esempio: https://example.com/hooks/skautik |
events | array | Sostituisce l'intero elenco di iscrizione invece di aggiungersi ad esso. esempio: ["property.created", "property.withdrawn"] |
active | boolean | Con false le consegne vengono messe in pausa; la registrazione e il suo segreto sopravvivono. esempio: true |
Corpo della richiesta
{ "active": false }https://api.skautik.com/v1/api/webhooks/{webhook_id}
PATCH /v1/api/webhooks/whk_1b7e6c19a139404cb173d23fcb3331c4 HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…
Content-Type: application/json
{ "active": false }/v1/api/webhooks/{webhook_id}/rotate-secretwebhooks:manageRuotare il segreto di firma
Emette un nuovo segreto e ferma subito quello vecchio.
È ciò a cui ricorrere se un segreto trapela. Il segreto precedente smette di funzionare nel momento in cui questa chiamata risponde, quindi le consegne firmate con esso falliranno la verifica: distribuisci il nuovo prima di ruotare, oppure accetta un'interruzione.
Parametri di percorso
| Nome | Tipo | Descrizione |
|---|---|---|
webhook_idobbligatorio | string | Identificatore del webhook. esempio: whk_1b7e6c19a139404cb173d23fcb3331c4 |
Risposta
{
"data": {
"secret": "whsec_4_j7SxmfWXaoJnLbkypLXAw-Pjs8J74_OyWb-oj7fik",
"note": "The previous secret stopped working immediately."
}
}https://api.skautik.com/v1/api/webhooks/{webhook_id}/rotate-secret
POST /v1/api/webhooks/whk_1b7e6c19a139404cb173d23fcb3331c4/rotate-secret HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…/v1/api/webhooks/{webhook_id}webhooks:manageEliminare un webhook
Ferma le consegne e dimentica l'endpoint.
Parametri di percorso
| Nome | Tipo | Descrizione |
|---|---|---|
webhook_idobbligatorio | string | Identificatore del webhook. esempio: whk_1b7e6c19a139404cb173d23fcb3331c4 |
https://api.skautik.com/v1/api/webhooks/{webhook_id}
DELETE /v1/api/webhooks/whk_1b7e6c19a139404cb173d23fcb3331c4 HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…/v1/api/webhooks/{webhook_id}/testwebhooks:manageInviare una consegna di prova
Fai scattare un evento sintetico per dimostrare che il tuo gestore funziona.
Invia un evento webhook.test con lo stesso comportamento di firma e di ripetizione di una consegna reale, così puoi verificare il controllo della firma prima che qualcosa di reale ne dipenda.
Parametri di percorso
| Nome | Tipo | Descrizione |
|---|---|---|
webhook_idobbligatorio | string | Identificatore del webhook. esempio: whk_1b7e6c19a139404cb173d23fcb3331c4 |
https://api.skautik.com/v1/api/webhooks/{webhook_id}/test
POST /v1/api/webhooks/whk_1b7e6c19a139404cb173d23fcb3331c4/test HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…/v1/api/webhooks/{webhook_id}/deliverieswebhooks:manageElencare le consegne
Tentativi recenti, i loro codici di risposta e lo stato dei nuovi tentativi.
Conservati per 30 giorni. È il posto dove guardare quando un gestore ha smesso di funzionare in silenzio.
Parametri di percorso
| Nome | Tipo | Descrizione |
|---|---|---|
webhook_idobbligatorio | string | Identificatore del webhook. esempio: whk_1b7e6c19a139404cb173d23fcb3331c4 |
Parametri di query
| Nome | Tipo | Descrizione |
|---|---|---|
status | enum | Filtra per esito. succeeded | failed | pending esempio: succeeded |
limit | integer | Quanti tentativi restituire, dal più recente. Con un tetto di 100. esempio: 100 |
https://api.skautik.com/v1/api/webhooks/{webhook_id}/deliveries
GET /v1/api/webhooks/whk_1b7e6c19a139404cb173d23fcb3331c4/deliveries?status=succeeded&limit=100 HTTP/1.1
Host: api.skautik.com
Authorization: Bearer sk_live_…