Webhooks allow the Gemini API to push real-time notifications to your server when asynchronous or Long-Running Operations (LROs) complete. This replaces the need to poll the API for status updates, reducing latency and overhead.
[View as markdown](https://ai.google.dev/static/api/webhooks.md.txt) [View the OpenAPI Spec](https://ai.google.dev/static/api/interactions.openapi.json)

> [!NOTE]
> This API is in Beta. Endpoints are under `/v1beta/`.

## CreateWebhook

post https://generativelanguage.googleapis.com/v1beta/webhooks Creates a new Webhook.
- [Request body](https://ai.google.dev/api/webhooks#CreateWebhook.request_body)
- [Response](https://ai.google.dev/api/webhooks#CreateWebhook.response)

### Request body

The request body contains data with the following structure:
name string (optional) Optional. The user-provided name of the webhook.
subscribed_events array (enum (string)) (required) Required. The events that the webhook is subscribed to.
Available events:
- batch.succeeded
- batch.expired
- batch.failed
- interaction.requires_action
- interaction.completed
- interaction.failed
- video.generated

Possible
values:

- `batch.succeeded`

  Batch processing finished successfully.
- `batch.expired`

  Batch has not been processed within the 48h timeframe.
- `batch.failed`

  Batch job failed.
- `interaction.requires_action`

  Interaction requires action (e.g., function calling).
- `interaction.completed`

  Interaction completed successfully.
- `interaction.failed`

  Interaction failed.
- `video.generated`

  Video generation completed.
uri string (required) Required. The URI to which webhook events will be sent.

### Response

If successful, the response body contains data with the following structure:
create_time string (optional) Output only. The timestamp when the webhook was created.
id string (optional) Output only. The ID of the webhook.
name string (optional) Optional. The user-provided name of the webhook.
new_signing_secret string (optional) Output only. The new signing secret for the webhook. Only populated on create.
signing_secrets array (SigningSecret) (optional) Output only. The signing secrets associated with this webhook.
Represents a signing secret used to verify webhook payloads.

#### Fields

expire_time string (optional) Output only. The expiration date of the signing secret.
truncated_secret string (optional) Output only. The truncated version of the signing secret.
state enum (string) (optional) Output only. The state of the webhook.

Possible
values:

- `enabled`

  The webhook is enabled.
- `disabled`

  The webhook is disabled by the user.
- `disabled_due_to_failed_deliveries`

  The webhook is disabled due to failed deliveries.
subscribed_events array (enum (string)) (optional) Required. The events that the webhook is subscribed to.
Available events:
- batch.succeeded
- batch.expired
- batch.failed
- interaction.requires_action
- interaction.completed
- interaction.failed
- video.generated

Possible
values:

- `batch.succeeded`

  Batch processing finished successfully.
- `batch.expired`

  Batch has not been processed within the 48h timeframe.
- `batch.failed`

  Batch job failed.
- `interaction.requires_action`

  Interaction requires action (e.g., function calling).
- `interaction.completed`

  Interaction completed successfully.
- `interaction.failed`

  Interaction failed.
- `video.generated`

  Video generation completed.
update_time string (optional) Output only. The timestamp when the webhook was last updated.
uri string (optional) Required. The URI to which webhook events will be sent.

### Example

<iframe src="https:///frame/api/webhooks_69282471c31e5b44a1648752557aa2af4e8dbbbb315209bef07a4181be63e898.frame" class="framebox inherit-locale " allow="clipboard-write https://" allowfullscreen is-upgraded></iframe>

#### Example Response

```json
{
  "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 Sends a ping event to a Webhook.
- [Path / Query parameters](https://ai.google.dev/api/webhooks#PingWebhook.PATH_PARAMETERS)
- [Request body](https://ai.google.dev/api/webhooks#PingWebhook.request_body)
- [Response](https://ai.google.dev/api/webhooks#PingWebhook.response)

### Path / Query Parameters

id string (required) Required. The ID of the webhook to ping.
Format: \`{webhook_id}\`

### Request body

The request body contains data with the following structure:

### Response

If successful, the response is empty.

### Example

<iframe src="https:///frame/api/webhooks_b95bbd961cbc1f974e712ccae89211dd075b24ac2cc8a650651a22545b5b2124.frame" class="framebox inherit-locale " allow="clipboard-write https://" allowfullscreen is-upgraded></iframe>

## RotateSigningSecret

post https://generativelanguage.googleapis.com/v1beta/webhooks/{id}:rotateSigningSecret Generates a new signing secret for a Webhook.
- [Path / Query parameters](https://ai.google.dev/api/webhooks#RotateSigningSecret.PATH_PARAMETERS)
- [Request body](https://ai.google.dev/api/webhooks#RotateSigningSecret.request_body)
- [Response](https://ai.google.dev/api/webhooks#RotateSigningSecret.response)

### Path / Query Parameters

id string (required) Required. The ID of the webhook for which to generate a signing secret.
Format: \`{webhook_id}\`

### Request body

The request body contains data with the following structure:
revocation_behavior enum (string) (optional) Optional. The revocation behavior for previous signing secrets.

Possible
values:

- `revoke_previous_secrets_after_h24`

  Generate a new signing secret and revoke all previous secrets after 24
  hours. Default and safest option for migrations.
- `revoke_previous_secrets_immediately`

  Revoke all previous secrets immediately. Use with caution as this can
  interrupt ongoing notifications.

### Response

If successful, the response body contains data with the following structure:
secret string (optional) Output only. The newly generated signing secret.

### Example

<iframe src="https:///frame/api/webhooks_818464b835d62e654dacde4866230273564a79efcc41e59e39847788b77694ad.frame" class="framebox inherit-locale " allow="clipboard-write https://" allowfullscreen is-upgraded></iframe>

#### Example Response

```json
{
  "secret": "string"
}
```

## ListWebhooks

get https://generativelanguage.googleapis.com/v1beta/webhooks Lists all Webhooks.
- [Path / Query parameters](https://ai.google.dev/api/webhooks#ListWebhooks.PATH_PARAMETERS)
- [Response](https://ai.google.dev/api/webhooks#ListWebhooks.response)

### Path / Query Parameters

page_size integer (optional) Optional. The maximum number of webhooks to return. The service may return fewer than
this value. If unspecified, at most 50 webhooks will be returned.
The maximum value is 1000.
page_token string (optional) Optional. A page token, received from a previous \`ListWebhooks\` call.
Provide this to retrieve the subsequent page.

### Response

If successful, the response body contains data with the following structure:
next_page_token string (optional) A token, which can be sent as \`page_token\` to retrieve the next page.
If this field is omitted, there are no subsequent pages.
webhooks array ([Webhook](https://ai.google.dev/api/webhooks#Resource:Webhook)) (optional) The webhooks.

### Example

<iframe src="https:///frame/api/webhooks_f6b0311fd35e32ced0fc0f9753399f557424c984e151cd6e4a1f535c81b8cd01.frame" class="framebox inherit-locale " allow="clipboard-write https://" allowfullscreen is-upgraded></iframe>

#### Example Response

```json
{
  "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} Gets a specific Webhook.
- [Path / Query parameters](https://ai.google.dev/api/webhooks#GetWebhook.PATH_PARAMETERS)
- [Response](https://ai.google.dev/api/webhooks#GetWebhook.response)

### Path / Query Parameters

id string (required) Required. The ID of the webhook to retrieve.

### Response

If successful, the response body contains data with the following structure:
create_time string (optional) Output only. The timestamp when the webhook was created.
id string (optional) Output only. The ID of the webhook.
name string (optional) Optional. The user-provided name of the webhook.
new_signing_secret string (optional) Output only. The new signing secret for the webhook. Only populated on create.
signing_secrets array (SigningSecret) (optional) Output only. The signing secrets associated with this webhook.
Represents a signing secret used to verify webhook payloads.

#### Fields

expire_time string (optional) Output only. The expiration date of the signing secret.
truncated_secret string (optional) Output only. The truncated version of the signing secret.
state enum (string) (optional) Output only. The state of the webhook.

Possible
values:

- `enabled`

  The webhook is enabled.
- `disabled`

  The webhook is disabled by the user.
- `disabled_due_to_failed_deliveries`

  The webhook is disabled due to failed deliveries.
subscribed_events array (enum (string)) (optional) Required. The events that the webhook is subscribed to.
Available events:
- batch.succeeded
- batch.expired
- batch.failed
- interaction.requires_action
- interaction.completed
- interaction.failed
- video.generated

Possible
values:

- `batch.succeeded`

  Batch processing finished successfully.
- `batch.expired`

  Batch has not been processed within the 48h timeframe.
- `batch.failed`

  Batch job failed.
- `interaction.requires_action`

  Interaction requires action (e.g., function calling).
- `interaction.completed`

  Interaction completed successfully.
- `interaction.failed`

  Interaction failed.
- `video.generated`

  Video generation completed.
update_time string (optional) Output only. The timestamp when the webhook was last updated.
uri string (optional) Required. The URI to which webhook events will be sent.

### Example

<iframe src="https:///frame/api/webhooks_bf5bb657875d7542a20a71b83fab6c7773c90c0df72740e2d003f2fccdcc5de8.frame" class="framebox inherit-locale " allow="clipboard-write https://" allowfullscreen is-upgraded></iframe>

#### Example Response

```json
{
  "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} Updates an existing Webhook.
- [Path / Query parameters](https://ai.google.dev/api/webhooks#UpdateWebhook.PATH_PARAMETERS)
- [Request body](https://ai.google.dev/api/webhooks#UpdateWebhook.request_body)
- [Response](https://ai.google.dev/api/webhooks#UpdateWebhook.response)

### Path / Query Parameters

id string (required) Required. The ID of the webhook to update.
update_mask string (optional) Optional. The list of fields to update.

### Request body

The request body contains data with the following structure:
name string (optional) Optional. The user-provided name of the webhook.
state enum (string) (optional) Optional. The state of the webhook.

Possible
values:

- `enabled`

  The webhook is enabled.
- `disabled`

  The webhook is disabled by the user.
- `disabled_due_to_failed_deliveries`

  The webhook is disabled due to failed deliveries.
subscribed_events array (enum (string)) (optional) Optional. The events that the webhook is subscribed to.
Available events:
- batch.succeeded
- batch.expired
- batch.failed
- interaction.requires_action
- interaction.completed
- interaction.failed
- video.generated

Possible
values:

- `batch.succeeded`

  Batch processing finished successfully.
- `batch.expired`

  Batch has not been processed within the 48h timeframe.
- `batch.failed`

  Batch job failed.
- `interaction.requires_action`

  Interaction requires action (e.g., function calling).
- `interaction.completed`

  Interaction completed successfully.
- `interaction.failed`

  Interaction failed.
- `video.generated`

  Video generation completed.
uri string (optional) Optional. The URI to which webhook events will be sent.

### Response

If successful, the response body contains data with the following structure:
create_time string (optional) Output only. The timestamp when the webhook was created.
id string (optional) Output only. The ID of the webhook.
name string (optional) Optional. The user-provided name of the webhook.
new_signing_secret string (optional) Output only. The new signing secret for the webhook. Only populated on create.
signing_secrets array (SigningSecret) (optional) Output only. The signing secrets associated with this webhook.
Represents a signing secret used to verify webhook payloads.

#### Fields

expire_time string (optional) Output only. The expiration date of the signing secret.
truncated_secret string (optional) Output only. The truncated version of the signing secret.
state enum (string) (optional) Output only. The state of the webhook.

Possible
values:

- `enabled`

  The webhook is enabled.
- `disabled`

  The webhook is disabled by the user.
- `disabled_due_to_failed_deliveries`

  The webhook is disabled due to failed deliveries.
subscribed_events array (enum (string)) (optional) Required. The events that the webhook is subscribed to.
Available events:
- batch.succeeded
- batch.expired
- batch.failed
- interaction.requires_action
- interaction.completed
- interaction.failed
- video.generated

Possible
values:

- `batch.succeeded`

  Batch processing finished successfully.
- `batch.expired`

  Batch has not been processed within the 48h timeframe.
- `batch.failed`

  Batch job failed.
- `interaction.requires_action`

  Interaction requires action (e.g., function calling).
- `interaction.completed`

  Interaction completed successfully.
- `interaction.failed`

  Interaction failed.
- `video.generated`

  Video generation completed.
update_time string (optional) Output only. The timestamp when the webhook was last updated.
uri string (optional) Required. The URI to which webhook events will be sent.

### Example

<iframe src="https:///frame/api/webhooks_1272af11ea040d47ebd8c7d4c164f72059f21909815dacebbd863fe7ed3e7114.frame" class="framebox inherit-locale " allow="clipboard-write https://" allowfullscreen is-upgraded></iframe>

#### Example Response

```json
{
  "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} Deletes a Webhook.
- [Path / Query parameters](https://ai.google.dev/api/webhooks#DeleteWebhook.PATH_PARAMETERS)
- [Response](https://ai.google.dev/api/webhooks#DeleteWebhook.response)

### Path / Query Parameters

id string (required) Required. The ID of the webhook to delete.
Format: \`{webhook_id}\`

### Response

If successful, the response is empty.

### Example

<iframe src="https:///frame/api/webhooks_db080921e9420d499a2f8b55744f5d62d5e52eb6c7afd75f3a092750f44a4640.frame" class="framebox inherit-locale " allow="clipboard-write https://" allowfullscreen is-upgraded></iframe>

## Resources

### Webhook

A Webhook resource.

#### Fields

create_time string (optional) Output only. The timestamp when the webhook was created.
id string (optional) Output only. The ID of the webhook.
name string (optional) Optional. The user-provided name of the webhook.
new_signing_secret string (optional) Output only. The new signing secret for the webhook. Only populated on create.
signing_secrets array (SigningSecret) (optional) Output only. The signing secrets associated with this webhook.
Represents a signing secret used to verify webhook payloads.

#### Fields

expire_time string (optional) Output only. The expiration date of the signing secret.
truncated_secret string (optional) Output only. The truncated version of the signing secret.
state enum (string) (optional) Output only. The state of the webhook.

Possible
values:

- `enabled`

  The webhook is enabled.
- `disabled`

  The webhook is disabled by the user.
- `disabled_due_to_failed_deliveries`

  The webhook is disabled due to failed deliveries.
subscribed_events array (enum (string)) (optional) Required. The events that the webhook is subscribed to.
Available events:
- batch.succeeded
- batch.expired
- batch.failed
- interaction.requires_action
- interaction.completed
- interaction.failed
- video.generated

Possible
values:

- `batch.succeeded`

  Batch processing finished successfully.
- `batch.expired`

  Batch has not been processed within the 48h timeframe.
- `batch.failed`

  Batch job failed.
- `interaction.requires_action`

  Interaction requires action (e.g., function calling).
- `interaction.completed`

  Interaction completed successfully.
- `interaction.failed`

  Interaction failed.
- `video.generated`

  Video generation completed.
update_time string (optional) Output only. The timestamp when the webhook was last updated.
uri string (optional) Required. The URI to which webhook events will be sent.