Gemini Webhooks API

I webhook consentono all'API Gemini di inviare notifiche in tempo reale al tuo server al termine delle operazioni asincrone o di lunga durata (LRO). In questo modo non è più necessario eseguire il polling dell'API per gli aggiornamenti di stato, riducendo la latenza e l'overhead.

Visualizza come Markdown Visualizza la specifica OpenAPI

CreateWebhook

post https://generativelanguage.googleapis.com/v1beta/webhooks

Crea un nuovo webhook.

Corpo della richiesta

Il corpo della richiesta contiene dati con la seguente struttura:

name string  (facoltativo)

Facoltativo. Il nome fornito dall'utente del webhook.

subscribed_events array (enum (string))  (required)

Obbligatorio. Gli eventi a cui è iscritto il webhook. Eventi disponibili: - batch.succeeded - batch.expired - batch.failed - interaction.requires_action - interaction.completed - interaction.failed - video.generated

Valori possibili:

  • batch.succeeded

    L'elaborazione batch è stata completata correttamente.

  • batch.expired

    Il batch non è stato elaborato entro il periodo di 48 ore.

  • batch.failed

    Il job batch non è riuscito.

  • interaction.requires_action

    L'interazione richiede un'azione (ad es. chiamata di funzione).

  • interaction.completed

    Interazione completata correttamente.

  • interaction.failed

    Interazione non riuscita.

  • video.generated

    Generazione del video completata.

uri string  (obbligatorio)

Obbligatorio. L'URI a cui verranno inviati gli eventi webhook.

Risposta

In caso di esito positivo, il corpo della risposta contiene dati con la seguente struttura:

create_time string  (facoltativo)

Solo output. Il timestamp di creazione del webhook.

id string  (facoltativo)

Solo output. L'ID del webhook.

name string  (facoltativo)

Facoltativo. Il nome fornito dall'utente del webhook.

new_signing_secret stringa  (facoltativo)

Solo output. Il nuovo secret di firma per il webhook. Compilato solo al momento della creazione.

signing_secrets array (SigningSecret)  (facoltativo)

Solo output. I segreti di firma associati a questo webhook.

Rappresenta un secret di firma utilizzato per verificare i payload webhook.

Campi

expire_time string  (facoltativo)

Solo output. La data di scadenza del segreto di firma.

truncated_secret string  (facoltativo)

Solo output. La versione troncata del secret di firma.

state enum (string)  (facoltativo)

Solo output. Lo stato del webhook.

Valori possibili:

  • enabled

    Il webhook è attivato.

  • disabled

    Il webhook è disattivato dall'utente.

  • disabled_due_to_failed_deliveries

    Il webhook è disabilitato a causa di mancate consegne.

subscribed_events array (enum (string))  (facoltativo)

Obbligatorio. Gli eventi a cui è iscritto il webhook. Eventi disponibili: - batch.succeeded - batch.expired - batch.failed - interaction.requires_action - interaction.completed - interaction.failed - video.generated

Valori possibili:

  • batch.succeeded

    L'elaborazione batch è stata completata correttamente.

  • batch.expired

    Il batch non è stato elaborato entro il periodo di 48 ore.

  • batch.failed

    Il job batch non è riuscito.

  • interaction.requires_action

    L'interazione richiede un'azione (ad es. chiamata di funzione).

  • interaction.completed

    Interazione completata correttamente.

  • interaction.failed

    Interazione non riuscita.

  • video.generated

    Generazione del video completata.

update_time string  (facoltativo)

Solo output. Timestamp dell'ultimo aggiornamento del webhook.

uri string  (facoltativo)

Obbligatorio. L'URI a cui verranno inviati gli eventi webhook.

Esempio

Esempio di risposta

{
  "create_time": "string",
  "id": "string",
  "name": "string",
  "new_signing_secret": "string",
  "signing_secrets": [
    {
      "expire_time": "string",
      "truncated_secret": "string"
    }
  ],
  "state": "enabled",
  "subscribed_events": [
    "batch.succeeded"
  ],
  "update_time": "string",
  "uri": "string"
}

PingWebhook

post https://generativelanguage.googleapis.com/v1beta/webhooks/{id}:ping

Invia un evento ping a un webhook.

Parametri percorso / query

id string  (obbligatorio)

Obbligatorio. L'ID del webhook da pingare. Formato: `{webhook_id}`

Corpo della richiesta

Il corpo della richiesta contiene dati con la seguente struttura:

Risposta

In caso di esito positivo, la risposta è vuota.

Esempio

RotateSigningSecret

post https://generativelanguage.googleapis.com/v1beta/webhooks/{id}:rotateSigningSecret

Genera un nuovo secret di firma per un webhook.

Parametri percorso / query

id string  (obbligatorio)

Obbligatorio. L'ID del webhook per cui generare un secret di firma. Formato: `{webhook_id}`

Corpo della richiesta

Il corpo della richiesta contiene dati con la seguente struttura:

revocation_behavior enum (string)  (facoltativo)

Facoltativo. Il comportamento di revoca per i secret di firma precedenti.

Valori possibili:

  • revoke_previous_secrets_after_h24

    Genera un nuovo secret di firma e revoca tutti i secret precedenti dopo 24 ore. Opzione predefinita e più sicura per le migrazioni.

  • revoke_previous_secrets_immediately

    Revoca immediatamente tutti i secret precedenti. Utilizza questa opzione con cautela, in quanto può interrompere le notifiche in corso.

Risposta

In caso di esito positivo, il corpo della risposta contiene dati con la seguente struttura:

secret string  (facoltativo)

Solo output. Il secret di firma appena generato.

Esempio

Esempio di risposta

{
  "secret": "string"
}

ListWebhooks

get https://generativelanguage.googleapis.com/v1beta/webhooks

Elenca tutti i webhook.

Parametri percorso / query

page_size integer  (facoltativo)

Facoltativo. Il numero massimo di webhook da restituire. Il servizio potrebbe restituire un numero inferiore a questo valore. Se non specificato, verranno restituiti al massimo 50 webhook. Il valore massimo è 1000.

page_token stringa  (facoltativo)

Facoltativo. Un token di pagina ricevuto da una precedente chiamata `ListWebhooks`. Forniscilo per recuperare la pagina successiva.

Risposta

In caso di esito positivo, il corpo della risposta contiene dati con la seguente struttura:

next_page_token stringa  (facoltativo)

Un token, che può essere inviato come `page_token` per recuperare la pagina successiva. Se questo campo viene omesso, non verranno visualizzate altre pagine.

webhooks array (Webhook)  (facoltativo)

I webhook.

Esempio

Esempio di risposta

{
  "next_page_token": "string",
  "webhooks": [
    {
      "create_time": "string",
      "id": "string",
      "name": "string",
      "new_signing_secret": "string",
      "signing_secrets": [
        {
          "expire_time": "string",
          "truncated_secret": "string"
        }
      ],
      "state": "enabled",
      "subscribed_events": [
        "batch.succeeded"
      ],
      "update_time": "string",
      "uri": "string"
    }
  ]
}

GetWebhook

get https://generativelanguage.googleapis.com/v1beta/webhooks/{id}

Recupera un webhook specifico.

Parametri percorso / query

id string  (obbligatorio)

Obbligatorio. L'ID del webhook da recuperare.

Risposta

In caso di esito positivo, il corpo della risposta contiene dati con la seguente struttura:

create_time string  (facoltativo)

Solo output. Il timestamp di creazione del webhook.

id string  (facoltativo)

Solo output. L'ID del webhook.

name string  (facoltativo)

Facoltativo. Il nome fornito dall'utente del webhook.

new_signing_secret stringa  (facoltativo)

Solo output. Il nuovo secret di firma per il webhook. Compilato solo al momento della creazione.

signing_secrets array (SigningSecret)  (facoltativo)

Solo output. I segreti di firma associati a questo webhook.

Rappresenta un secret di firma utilizzato per verificare i payload webhook.

Campi

expire_time string  (facoltativo)

Solo output. La data di scadenza del segreto di firma.

truncated_secret string  (facoltativo)

Solo output. La versione troncata del secret di firma.

state enum (string)  (facoltativo)

Solo output. Lo stato del webhook.

Valori possibili:

  • enabled

    Il webhook è attivato.

  • disabled

    Il webhook è disattivato dall'utente.

  • disabled_due_to_failed_deliveries

    Il webhook è disabilitato a causa di mancate consegne.

subscribed_events array (enum (string))  (facoltativo)

Obbligatorio. Gli eventi a cui è iscritto il webhook. Eventi disponibili: - batch.succeeded - batch.expired - batch.failed - interaction.requires_action - interaction.completed - interaction.failed - video.generated

Valori possibili:

  • batch.succeeded

    L'elaborazione batch è stata completata correttamente.

  • batch.expired

    Il batch non è stato elaborato entro il periodo di 48 ore.

  • batch.failed

    Il job batch non è riuscito.

  • interaction.requires_action

    L'interazione richiede un'azione (ad es. chiamata di funzione).

  • interaction.completed

    Interazione completata correttamente.

  • interaction.failed

    Interazione non riuscita.

  • video.generated

    Generazione del video completata.

update_time string  (facoltativo)

Solo output. Timestamp dell'ultimo aggiornamento del webhook.

uri string  (facoltativo)

Obbligatorio. L'URI a cui verranno inviati gli eventi webhook.

Esempio

Esempio di risposta

{
  "create_time": "string",
  "id": "string",
  "name": "string",
  "new_signing_secret": "string",
  "signing_secrets": [
    {
      "expire_time": "string",
      "truncated_secret": "string"
    }
  ],
  "state": "enabled",
  "subscribed_events": [
    "batch.succeeded"
  ],
  "update_time": "string",
  "uri": "string"
}

UpdateWebhook

patch https://generativelanguage.googleapis.com/v1beta/webhooks/{id}

Aggiorna un webhook esistente.

Parametri percorso / query

id string  (obbligatorio)

Obbligatorio. L'ID del webhook da aggiornare.

update_mask string  (facoltativo)

Facoltativo. L'elenco dei campi da aggiornare.

Corpo della richiesta

Il corpo della richiesta contiene dati con la seguente struttura:

name string  (facoltativo)

Facoltativo. Il nome fornito dall'utente del webhook.

state enum (string)  (facoltativo)

Facoltativo. Lo stato del webhook.

Valori possibili:

  • enabled

    Il webhook è attivato.

  • disabled

    Il webhook è disattivato dall'utente.

  • disabled_due_to_failed_deliveries

    Il webhook è disabilitato a causa di mancate consegne.

subscribed_events array (enum (string))  (facoltativo)

Facoltativo. Gli eventi a cui è iscritto il webhook. Eventi disponibili: - batch.succeeded - batch.expired - batch.failed - interaction.requires_action - interaction.completed - interaction.failed - video.generated

Valori possibili:

  • batch.succeeded

    L'elaborazione batch è stata completata correttamente.

  • batch.expired

    Il batch non è stato elaborato entro il periodo di 48 ore.

  • batch.failed

    Il job batch non è riuscito.

  • interaction.requires_action

    L'interazione richiede un'azione (ad es. chiamata di funzione).

  • interaction.completed

    Interazione completata correttamente.

  • interaction.failed

    Interazione non riuscita.

  • video.generated

    Generazione del video completata.

uri string  (facoltativo)

Facoltativo. L'URI a cui verranno inviati gli eventi webhook.

Risposta

In caso di esito positivo, il corpo della risposta contiene dati con la seguente struttura:

create_time string  (facoltativo)

Solo output. Il timestamp di creazione del webhook.

id string  (facoltativo)

Solo output. L'ID del webhook.

name string  (facoltativo)

Facoltativo. Il nome fornito dall'utente del webhook.

new_signing_secret stringa  (facoltativo)

Solo output. Il nuovo secret di firma per il webhook. Compilato solo al momento della creazione.

signing_secrets array (SigningSecret)  (facoltativo)

Solo output. I segreti di firma associati a questo webhook.

Rappresenta un secret di firma utilizzato per verificare i payload webhook.

Campi

expire_time string  (facoltativo)

Solo output. La data di scadenza del segreto di firma.

truncated_secret string  (facoltativo)

Solo output. La versione troncata del secret di firma.

state enum (string)  (facoltativo)

Solo output. Lo stato del webhook.

Valori possibili:

  • enabled

    Il webhook è attivato.

  • disabled

    Il webhook è disattivato dall'utente.

  • disabled_due_to_failed_deliveries

    Il webhook è disabilitato a causa di mancate consegne.

subscribed_events array (enum (string))  (facoltativo)

Obbligatorio. Gli eventi a cui è iscritto il webhook. Eventi disponibili: - batch.succeeded - batch.expired - batch.failed - interaction.requires_action - interaction.completed - interaction.failed - video.generated

Valori possibili:

  • batch.succeeded

    L'elaborazione batch è stata completata correttamente.

  • batch.expired

    Il batch non è stato elaborato entro il periodo di 48 ore.

  • batch.failed

    Il job batch non è riuscito.

  • interaction.requires_action

    L'interazione richiede un'azione (ad es. chiamata di funzione).

  • interaction.completed

    Interazione completata correttamente.

  • interaction.failed

    Interazione non riuscita.

  • video.generated

    Generazione del video completata.

update_time string  (facoltativo)

Solo output. Timestamp dell'ultimo aggiornamento del webhook.

uri string  (facoltativo)

Obbligatorio. L'URI a cui verranno inviati gli eventi webhook.

Esempio

Esempio di risposta

{
  "create_time": "string",
  "id": "string",
  "name": "string",
  "new_signing_secret": "string",
  "signing_secrets": [
    {
      "expire_time": "string",
      "truncated_secret": "string"
    }
  ],
  "state": "enabled",
  "subscribed_events": [
    "batch.succeeded"
  ],
  "update_time": "string",
  "uri": "string"
}

DeleteWebhook

delete https://generativelanguage.googleapis.com/v1beta/webhooks/{id}

Elimina un webhook.

Parametri percorso / query

id string  (obbligatorio)

Obbligatorio. L'ID del webhook da eliminare. Formato: `{webhook_id}`

Risposta

In caso di esito positivo, la risposta è vuota.

Esempio

Risorse

Webhook

Una risorsa webhook.

Campi

create_time string  (facoltativo)

Solo output. Il timestamp di creazione del webhook.

id string  (facoltativo)

Solo output. L'ID del webhook.

name string  (facoltativo)

Facoltativo. Il nome fornito dall'utente del webhook.

new_signing_secret stringa  (facoltativo)

Solo output. Il nuovo secret di firma per il webhook. Compilato solo al momento della creazione.

signing_secrets array (SigningSecret)  (facoltativo)

Solo output. I segreti di firma associati a questo webhook.

Rappresenta un secret di firma utilizzato per verificare i payload webhook.

Campi

expire_time string  (facoltativo)

Solo output. La data di scadenza del segreto di firma.

truncated_secret string  (facoltativo)

Solo output. La versione troncata del secret di firma.

state enum (string)  (facoltativo)

Solo output. Lo stato del webhook.

Valori possibili:

  • enabled

    Il webhook è attivato.

  • disabled

    Il webhook è disattivato dall'utente.

  • disabled_due_to_failed_deliveries

    Il webhook è disabilitato a causa di mancate consegne.

subscribed_events array (enum (string))  (facoltativo)

Obbligatorio. Gli eventi a cui è iscritto il webhook. Eventi disponibili: - batch.succeeded - batch.expired - batch.failed - interaction.requires_action - interaction.completed - interaction.failed - video.generated

Valori possibili:

  • batch.succeeded

    L'elaborazione batch è stata completata correttamente.

  • batch.expired

    Il batch non è stato elaborato entro il periodo di 48 ore.

  • batch.failed

    Il job batch non è riuscito.

  • interaction.requires_action

    L'interazione richiede un'azione (ad es. chiamata di funzione).

  • interaction.completed

    Interazione completata correttamente.

  • interaction.failed

    Interazione non riuscita.

  • video.generated

    Generazione del video completata.

update_time string  (facoltativo)

Solo output. Timestamp dell'ultimo aggiornamento del webhook.

uri string  (facoltativo)

Obbligatorio. L'URI a cui verranno inviati gli eventi webhook.