POST/v1/webhooks

Creare un webhook

create_webhook

L’URL deve usare https e il suo host deve risolversi in indirizzi pubblici. Le reti private (RFC 1918), di loopback, link-local, dei metadati cloud e le altre reti per usi speciali vengono rifiutate sia alla registrazione sia a ogni connessione. Il segreto di firma viene mostrato una sola volta nella risposta (secret); in seguito può solo essere ruotato. Un’organizzazione può avere al massimo 20 webhook.

La sottoscrizione elenca tipi di evento e maschere di dominio (card.*, *). L’accesso si imposta come per una chiave API: role, data_profile_id e collection_ids. Un evento su un oggetto che il ruolo, il profilo dati o le raccolte non possono vedere non viene consegnato. tags limita gli eventi delle schede alle schede con almeno uno dei tag. payload: thin invia gli eventi senza data. Le intestazioni personalizzate (headers) e l’autorizzazione in uscita (auth) vengono salvate cifrate; le risposte contengono solo i nomi delle intestazioni e i flag value_set e auth_set.

Autenticazione

Invia una chiave API nell’intestazione Authorization: Authorization: Bearer <chiave>.

Parametri di intestazione

Idempotency-Keystring
Chiave per ripetere in sicurezza una scrittura: da 1 a 255 caratteri ASCII stampabili; si consiglia un UUID v4 per ogni operazione logica. Un nuovo tentativo con la stessa chiave entro 24 ore non esegue di nuovo l’operazione: restituisce la risposta salvata (stato, intestazioni e corpo) con l’intestazione Idempotency-Replayed: true. La stessa chiave con un metodo, un percorso, un Content-Type o un corpo diversi restituisce 409 api.idempotency_mismatch; mentre la prima richiesta è ancora in esecuzione, 409 api.idempotency_in_progress con Retry-After: 1. Dopo una risposta 5xx o 429 la chiave viene rilasciata e un nuovo tentativo esegue di nuovo l’operazione. La chiave vale per l’organizzazione e per chi effettua la chiamata (chiave API, utente o chiave di una fonte personalizzata).
length ≥ 1, length ≤ 255

Corpo della richiesta

application/json

Oggetto: WebhookCreate

urlstringobbligatorio
URL del ricevitore, solo https://, fino a 2048 caratteri.
length ≤ 2048
descriptionstring
length ≤ 200
eventsarray of WebhookEventFilterobbligatorio
items ≥ 1
roleWebhookRole
data_profile_idinteger | null
collection_idsarray of integer
Raccolte sulle quali il webhook riceve eventi. Nessun valore o un elenco vuoto indica tutte le raccolte disponibili per il ruolo e il profilo dati. Una chiave a sua volta limitata a determinate raccolte crea un webhook solo con un elenco non vuoto delle proprie raccolte. Senza questo campo, con un elenco vuoto o con una raccolta fuori dal suo elenco, la richiesta restituisce 403 webhooks.collections_outside_key.
items ≤ 200
tagsarray of string
items ≤ 50
payloadWebhookPayloadMode
headersarray of WebhookHeaderInput
items ≤ 10
authWebhookAuthInput

Risposte

201Webhook creato. È l’unica volta in cui viene mostrato `secret`.

Intestazioni della risposta

RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.
Idempotency-Replayed
true indica che la risposta è stata ripetuta da quella salvata per questa Idempotency-Key: l’operazione non è stata eseguita di nuovo.

application/json

Oggetto: WebhookCreated

idintegerobbligatorio
urlstringobbligatorio
descriptionstringobbligatorio
eventsarray of WebhookEventFilterobbligatorio
activebooleanobbligatorio
statusWebhookStatusobbligatorio
paused_atstring (date-time) | null
paused_reasonstring | null
failures: 10 tentativi non riusciti di seguito; feature_disabled: il piano non include i webhook.
disabled_reasonstring | null
gone: il ricevitore ha risposto 410; manual: disattivato da un amministratore.
Valori ammessi: gonemanualnull
disabled_atstring (date-time) | null
roleWebhookRoleobbligatorio
data_profile_idinteger | null
Profilo dati del webhook (null indica nessun profilo, come per una chiave API con lo stesso ruolo).
collection_idsarray of integerobbligatorio
Raccolte sui cui eventi il webhook riceve notifiche; vuoto indica tutte le raccolte disponibili per il ruolo e il profilo dati.
tagsarray of stringobbligatorio
Eventi delle schede solo per le schede con almeno uno di questi tag; vuoto indica nessun filtro.
payloadWebhookPayloadModeobbligatorio
headersarray of WebhookHeaderobbligatorio
auth_typestring | null
Tipo di autorizzazione in uscita (null indica nessuna).
Valori ammessi: bearerbasicnull
auth_setbooleanobbligatorio
Indica se è impostata un’autorizzazione in uscita (i valori non vengono mai restituiti).
previous_secret_valid_untilstring (date-time) | null
Fino a quando le consegne vengono firmate anche con il segreto precedente (null indica che non c’è sovrapposizione).
healthWebhookHealth
consecutive_failuresintegerobbligatorio
last_delivery_atstring (date-time) | null
last_success_atstring (date-time) | null
last_errorstring | null
created_byinteger | null
created_by_namestring | null
created_atstring (date-time)obbligatorio
updated_atstring (date-time)obbligatorio
secretstringobbligatorio
whsec_ seguito da 32 byte in base64 (i nuovi segreti usano l’alfabeto standard con padding, quelli meno recenti usano base64url). Conservalo sul lato del ricevitore; non compare mai più nelle risposte dell’API. La chiave di firma di Standard Webhooks è la decodifica base64 della parte dopo whsec_.
previous_valid_untilstring (date-time) | null
Fino a quando il segreto precedente viene ancora accettato (dopo una rotazione). null alla creazione.

400La richiesta non è valida: il valore di un parametro o lo stato dell’oggetto non consente l’azione (`detail` è un messaggio).

Intestazioni della risposta

RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

401Non sono state inviate credenziali (né un cookie di sessione né una chiave API), oppure la chiave non è stata trovata.

Intestazioni della risposta

RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

403L’azione non è consentita: il ruolo non è sufficiente, manca l’accesso alla raccolta o alla scheda, la richiesta viene eseguita in modalità “View as”, oppure l’organizzazione è sospesa o eliminata (`detail` è un oggetto con `code: org_suspended | org_deleted`).

Intestazioni della risposta

RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

409Lo stato dell’oggetto non consente l’azione, ad esempio un duplicato, un’indicizzazione in corso o un job già elaborato.

Intestazioni della risposta

RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

422Errore di validazione: il corpo o i parametri non corrispondono allo schema (`detail` è un elenco di errori di validazione), oppure il valore di un parametro è fuori dall’intervallo ammesso (`detail` è un messaggio).

Intestazioni della risposta

RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

429Troppe richieste (`api.rate_limited`), la quota dell’organizzazione per il minuto, il giorno o il mese è esaurita (`api.quota_exceeded`; `error.details` contiene `quota`, `limit` e `reset_at`), è stato raggiunto il limite dell’organizzazione, oppure il servizio delle risposte è occupato (`answers.engine_busy`). Attendi il tempo indicato nell’intestazione `Retry-After`.

Intestazioni della risposta

Retry-After
Numero di secondi da attendere prima di ripetere la richiesta.
RateLimit-Policy
Limiti in vigore, nel formato della bozza IETF draft-ietf-httpapi-ratelimit-headers: elementi separati da virgole "<name>";q=<quota>;w=<window in seconds>. key è la frequenza delle richieste della chiave API (la quota è il burst, la finestra è il tempo necessario a ricaricarla completamente; per una sessione è user, senza credenziali ip); minute, day e month sono le quote dell’organizzazione per il minuto, il giorno e il mese di calendario in UTC.
RateLimit
Quanto resta di ciascun limite di RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.
X-RateLimit-Limit
Limite della voce più restrittiva di RateLimit-Policy (quella con meno richieste rimanenti).
X-RateLimit-Remaining
Richieste rimanenti nel limite più restrittivo.
X-RateLimit-Reset
Secondi che mancano all’azzeramento del limite più restrittivo.

application/json

Oggetto: Error

Codici di errore

Codici che questo endpoint può restituire in error.code, oltre ai codici generali di ogni richiesta.

Nuovi tentativi sicuri

Invia un’intestazione Idempotency-Key (per esempio un UUID) con ogni POST e PATCH. Un nuovo tentativo con la stessa chiave entro 24 ore restituisce la risposta salvata invece di eseguire di nuovo la richiesta.

Limiti di frequenza

Le risposte contengono le intestazioni RateLimit e RateLimit-Policy e le precedenti X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Una risposta 429 contiene Retry-After in secondi: attendi e riprova.

← webhooks · Riferimento API

curl -X POST 'https://api.sursa.com/v1/webhooks' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/webhooks/sursa","events":["card.*"]}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Prova

Chiave API

La chiave resta nella memoria di questa scheda del browser e viene inviata solo a https://api.sursa.com.

Le richieste vengono eseguite sui dati reali della tua organizzazione.

Idempotency-Key header

Idempotency-Key

Se il campo è vuoto, per ogni richiesta viene generata una nuova chiave.

Corpo della richiesta (JSON)