Webhooks: riferimento API, endpoint ed esempi

OpenAPI YAML OpenAPI JSON problemi YAML Panoramica dell’API

Questo gruppo ha 9 operazioni, generate da api/openapi.yaml. Filtra per percorso, azione o autenticazione. Ogni endpoint elenca i suoi input; espandilo per vedere un modello di richiesta e i codici di risposta. I modelli richiedono i tuoi valori e un corpo valido secondo lo schema.

Sostituisci i segnaposto maiuscoli con i tuoi valori. Per una richiesta JSON, salva un corpo che corrisponde allo schema in request.json. Gli esempi di cookie usano un cookie jar locale da una sessione autenticata.

Webhook: consegna eventi firmata

GET/api/webhooks¶

Elenca i webhook

Elenca le notifiche webhook del progetto nel formato webhook, dalla meno recente (al massimo 50); GET /api/notifications elenca ogni canale. Il segreto di firma non viene mai restituito qui. Richiede la capability project; una credenziale limitata ai report viene rifiutata con 403 forbidden, perché la risposta include gli URL di ricezione.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: listWebhooks

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.

Modello richiesta e risposte

shell · modello richiesta

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/webhooks'

Risposte

Stato	Significato	Corpo e intestazioni
200	I webhook del progetto.	WebhookList (application/json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

POST/api/webhooks¶

Crea webhook

Crea un webhook che riceve gli eventi durevoli del progetto come POST HTTPS firmati. L’URL deve essere https su un host pubblico Internet: un IP letterale o ogni risposta DNS attuale del nome deve essere pubblica (privati, loopback, link-local, CGNAT, IPv6 fuori 2000::/3, documentazione e altri intervalli riservati sono rifiutati con webhook_url_rejected).

La porta deve essere 443 (default) o 8443, altrimenti webhook_url_rejected. L’host è risolto e controllato di nuovo prima di ogni consegna e la connessione è stabilita esattamente all’indirizzo controllato, quindi una risposta DNS che cambia dopo non può reindirizzare le consegne. event_types elenca tipi esatti di eventi (screen.online) o prefissi terminanti in .* (screen.*).

Un’organizzazione ha al massimo 50 notifiche su tutti i canali (webhook_limit_reached). Il server genera il segreto di firma e lo restituisce solo in questa risposta e in rotate-secret; conservalo. Un nuovo tentativo identico con la stessa Idempotency-Key restituisce questa stessa risposta, segreto incluso, per ventiquattro ore.

La consegna parte dal primo evento successivo a notification.created.

Autenticazione: projectBearer
Corpo della richiesta: WebhookWrite
ID operazione: createWebhook

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Campi del corpo della richiesta

Campo	Descrizione
url (obbligatorio, stringa)	URL https su host pubblico Internet, porta 443 (default) o 8443. Nessun userinfo o frammento. maxLength: 2048 formato: "uri"
event_types (obbligatorio, WebhookEventTypes)	Tipi di evento esatti come screen.online, oppure prefissi che terminano con .* come screen.* (ogni tipo che inizia con screen.). notification.test non viene mai distribuito da una sottoscrizione; viene inviato solo da POST /api/webhooks/{id}/test.
abilitato (opzionale, booleano)	predefinito: true
descrizione (opzionale, stringa)	maxLength: 200

Modello richiesta e risposte

shell · modello richiesta

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/webhooks'

Risposte

Stato	Significato	Corpo e intestazioni
201	Creato. Il segreto è mostrato solo qui e su ruota-segreto.	WebhookWithSecret (application/json); intestazioni: Cache-Control
400	invalid_request o webhook_url_rejected.	Problema (application/problem+json)
409	webhook_limit_reached, idempotency_mismatch o resource_conflict quando il progetto non appartiene a nessuna organizzazione.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

GET/api/webhooks/{id}¶

Ottieni webhook

Richiede la capacità progetto; una credenziale solo report è rifiutata 403 forbidden, perché la risposta include URL ricevitore.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: getWebhook

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio

Modello richiesta e risposte

shell · modello richiesta

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/webhooks/RESOURCE_ID'

Risposte

Stato	Significato	Corpo e intestazioni
200	Un webhook.	Webhook (application/json); intestazioni: ETag
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

PATCH/api/webhooks/{id}¶

Aggiorna webhook

Modifica uno qualsiasi di url, event_types, enabled e description (una descrizione vuota la cancella). Un nuovo url è verificato come in creazione.

Impostare enabled true su un webhook disabilitato cancella il suo stato di errore e avvia la consegna dall’evento che registra la modifica; gli eventi mentre era disabilitato non vengono riprodotti, e le consegne ancora in sospeso prima della disabilitazione falliscono con webhook_disabled. Impostare enabled false fa fallire le consegne in sospeso con webhook_disabled.

Aggiunge l'evento notification.updated. If-Match protegge la revisione.

Autenticazione: projectBearer
Corpo della richiesta: WebhookPatch
ID operazione: updateWebhook

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
If-Match	intestazione	opzionale	Revisione positiva opzionale della risorsa. Ometti per scrivere la risorsa corrente; una revisione obsoleta fornita è revision_conflict.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Campi del corpo della richiesta

Campo	Descrizione
url (opzionale, stringa)	maxLength: 2048 format: "uri"
event_types (opzionale, WebhookEventTypes)	Tipi di evento esatti come screen.online, oppure prefissi che terminano con .* come screen.* (ogni tipo che inizia con screen.). notification.test non viene mai distribuito da una sottoscrizione; viene inviato solo da POST /api/webhooks/{id}/test.
abilitato (opzionale, booleano)
descrizione (opzionale, stringa)	Una stringa vuota cancella la descrizione. maxLength: 200

Modello richiesta e risposte

shell · modello richiesta

curl --request PATCH --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --header 'Content-Type: application/json' --data '@request.json' 'https://screenrig.ai/api/webhooks/RESOURCE_ID'

Risposte

Stato	Significato	Corpo e intestazioni
200	Webhook aggiornato.	Webhook (application/json); intestazioni: ETag
400	invalid_request o webhook_url_rejected.	Problema (application/problem+json)
412	revision_conflict — If-Match è obsoleto; current_revision dell’errore riporta la revisione corrente.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

ELIMINA/api/webhooks/{id}¶

Elimina webhook

Elimina il webhook e aggiunge l'evento notification.deleted. Le sue consegne in sospeso vengono contrassegnate come fallite con webhook_deleted; il suo registro delle consegne non è più consultabile e scade con il periodo di conservazione degli eventi.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: deleteWebhook

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
If-Match	intestazione	opzionale	Revisione positiva opzionale della risorsa. Ometti per scrivere la risorsa corrente; una revisione obsoleta fornita è revision_conflict.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Modello richiesta e risposte

shell · modello richiesta

curl --request DELETE --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/webhooks/RESOURCE_ID'

Risposte

Stato	Significato	Corpo e intestazioni
204	Eliminato.	nessun corpo; intestazioni: Cache-Control
412	revision_conflict — If-Match è obsoleto; current_revision dell’errore riporta la revisione corrente.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

POST/api/webhooks/{id}/rotate-secret¶

Ruota Webhook Secret

Sostituisce il segreto di firma e restituisce quello nuovo; il vecchio segreto smette di firmare subito: ogni tentativo che firma dopo il commit di questa operazione usa il nuovo segreto, e al massimo un tentativo per webhook già in corso può ancora arrivare firmato con quello vecchio, quindi accetta entrambi per un breve periodo. Aggiunge l'evento notification.updated con details.changed [secret].

Un retry esatto con la stessa Idempotency-Key restituisce lo stesso nuovo segreto per ventiquattro ore.

Autenticazione: projectBearer
Corpo della richiesta: nessuno
ID operazione: rotateWebhookSecret

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
If-Match	intestazione	opzionale	Revisione positiva opzionale della risorsa. Ometti per scrivere la risorsa corrente; una revisione obsoleta fornita è revision_conflict.
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Modello richiesta e risposte

shell · modello richiesta

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/webhooks/RESOURCE_ID/rotate-secret'

Risposte

Stato	Significato	Corpo e intestazioni
200	Il webhook e il suo nuovo segreto.	WebhookWithSecret (application/json); intestazioni: Cache-Control
412	revision_conflict — If-Match è obsoleto; current_revision dell’errore riporta la revisione corrente.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

POST/api/webhooks/{id}/test¶

Test webhook

Aggiunge un evento di progetto notification.test e mette in coda una consegna di tale evento solo a questo webhook (nessun altro webhook riceve notification.test). Funziona anche su un webhook disattivato; la consegna viene tentata una sola volta senza nuovi tentativi, viene conteggiata come qualsiasi altra consegna e non modifica mai lo stato di errore del webhook. Interroga periodicamente il registro delle consegne per conoscerne l'esito.

Autenticazione: projectBearer
Corpo della richiesta: nessuno
ID operazione: testWebhook

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
Idempotency-Key	intestazione	opzionale	Ometti per un’operazione fresca. Fornisci e riutilizza una chiave per deduplicare i retry; la CLI gestisce automaticamente le chiavi.

Modello richiesta e risposte

shell · modello richiesta

curl --request POST --header 'Authorization: Bearer [SCREENRIG_TOKEN]' 'https://api.screenrig.ai/api/webhooks/RESOURCE_ID/test'

Risposte

Stato	Significato	Corpo e intestazioni
202	La consegna di test in coda.	WebhookDelivery (application/json); intestazioni: RateLimit-Policy, RateLimit
429	Problema rate_limited stabile. Ritenta solo dopo l'intervallo Retry-After autorevole. I dinieghi a finestra fissa includono anche RateLimit-Policy e membri RateLimit applicabili; i dinieghi per concorrenza e budget byte omettono tali divulgazioni opzionali.	Problema (application/problem+json); intestazioni: Retry-After, RateLimit-Policy, RateLimit
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

GET/api/webhooks/{id}/deliveries¶

Elenca le consegne webhook

Il registro di consegna del webhook, evento più recente per primo. Una riga per (webhook, evento); i ritenti aggiornano la riga e GET .../deliveries/{delivery_id}/attempts elenca i tentativi più recenti. Le righe sono conservate come gli eventi (la conservazione eventi del piano, almeno la finestra di ritentativo di 24 ore). Passa next_cursor come parametro before per la pagina successiva.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: listWebhookDeliveries

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
before	query	opzionale	next_cursor della pagina precedente delle consegne.
limite	query	opzionale

Modello richiesta e risposte

shell · modello richiesta

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/webhooks/RESOURCE_ID/deliveries'

Risposte

Stato	Significato	Corpo e intestazioni
200	Una pagina di consegne.	WebhookDeliveryList (application/json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)

GET/api/webhooks/{id}/deliveries/{delivery_id}/attempts¶

Elenca i tentativi di consegna webhook

I tentativi di una consegna, dal più recente, i 20 più recenti, conservati con la riga della consegna e per tutto il tempo. Ognuno ha il numero del tentativo, quando è terminato, lo stato HTTP del ricevitore (null se nessuno ha risposto), la classe di errore (null se successo) e la sua durata. Corpi e intestazioni di risposta non sono mai conservati. Una consegna registrata prima che i tentativi fossero conservati non ne elenca nessuno.

Una consegna che non è di questo webhook, o di un webhook di un altro progetto, è not_found.

Autenticazione: projectBearer O dashboardSession
Corpo della richiesta: nessuno
ID operazione: listWebhookDeliveryAttempts

Parametri

Nome	Invia	Obbligatorio?	Descrizione
ScreenRig-Project	intestazione	opzionale	Deprecato per una release. Deve essere coerente con le concessioni JWT dei progetti; aggiunge intestazioni Deprecation e Warning. Nessuno scambio di token.
id	path	obbligatorio
delivery_id	path	obbligatorio	L’id di una delle consegne del webhook.

Modello richiesta e risposte

shell · modello richiesta

curl --request GET --header 'Authorization: Bearer [SCREENRIG_TOKEN]' --cookie cookies.txt --cookie-jar cookies.txt 'https://screenrig.ai/api/webhooks/RESOURCE_ID/deliveries/DELIVERY_ID/attempts'

Risposte

Stato	Significato	Corpo e intestazioni
200	I tentativi mantenuti della consegna.	WebhookDeliveryAttemptList (application/json)
404	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)
predefinito	Risposta problema stabile RFC 9457. Un 421 server_draining ha Retry-After di 1 secondo, un 500 not_ready o dependency_unavailable ha 5, e un 500 manifest_degraded ha 60, salvo valore più specifico impostato dal gestore.	Problema (application/problem+json)