--- title: "Update Webhook" method: PUT path: "/webhooks/{webhook_id}" tags: ["Webhooks"] --- # Update Webhook `PUT /webhooks/{webhook_id}` Update an existing `Webhook` to: - Enable or disable a `Webhook`. Disabled webhooks stop receiving events at the configured URL. - Add [authentication to a Webhook](/additional-resources/developers/webhooks/integrating-into-webhooks#creating-authenticated-webhooks) - [Override default event filters](/additional-resources/developers/webhooks/integrating-into-webhooks#filtering-webhooks) by specifying the list of events you are interested in receiving ## Request body - union - UpdateWebhookAllFields - `authentication` Authentication — Credentials included in webhook POST requests so your server can confirm each request originated from Finix. To learn about the different authentication methods, see [Managing Webhooks via API](/additional-resources/developers/webhooks/integrating-into-webhooks#managing-webhooks-via-api). - `basic` object — A basic authentication configuration provided by the user. - `password` string — A user-provided basic authentication password. - `username` string — A user-provided basic authentication username. - `bearer` object — A bearer authentication configuration. - `token` string — The string that Finix will send as the bearer token. - `type` 'NONE' | 'BASIC' | 'BEARER' — The type of authentication the `Webhook` will use: - `NONE` - No authentication will be used. - `BASIC` - Basic authentication. - `BEARER` - OAuth2 Bearer Token. - `enabled` boolean — Enable or disable the `Webhook`. Disabled webhooks will not receive events. - `true` - webhook events are sent to the `url`. - `false` - webhook events are not sent to the `url`. - `enabled_events` object[] — A list of webhook events to enable for API entities. There can be only one enabled event object per `entity`. This list is optional and overrides default webhook events. See [Webhook Events](/additional-resources/developers/webhooks/webhook-events) to learn which events are automatically subscribed at creation. When included in a PUT request, this list replaces all previously configured events. - `entity` string — The API entity for which you want to receive webhook events. - `types` string[] — A list of webhook event types you want to receive for the specified `entity`. See the [Webhook Events](/additional-resources/developers/webhooks/webhook-events) guide to learn which values are accepted for each entity. - `generate_new_secret` boolean — Triggers rotation of the `Webhook`'s HMAC signing key. When `true`, the current key is stored as the previous key, a new key is generated, and the new secret is returned in the response. Requires `previous_secret_active_hours` to be set. - `nickname` string — A human-readable name for the `Webhook`. - `previous_secret_active_hours` integer — Controls how long the old signing key remains valid alongside the new one during rotation. Both keys can verify signatures during this window. A value of `0` means the old key expires immediately. Required when `generate_new_secret` is `true`; forbidden otherwise. - `url` string — The HTTP or HTTPS URL to receive events. When an event occurs, Finix sends a POST request to this URL with the webhook event payload. - UpdateWebhookAuthentication - `authentication` Authentication — Credentials included in webhook POST requests so your server can confirm each request originated from Finix. To learn about the different authentication methods, see [Managing Webhooks via API](/additional-resources/developers/webhooks/integrating-into-webhooks#managing-webhooks-via-api). - `basic` object — A basic authentication configuration provided by the user. - `password` string — A user-provided basic authentication password. - `username` string — A user-provided basic authentication username. - `bearer` object — A bearer authentication configuration. - `token` string — The string that Finix will send as the bearer token. - `type` 'NONE' | 'BASIC' | 'BEARER' — The type of authentication the `Webhook` will use: - `NONE` - No authentication will be used. - `BASIC` - Basic authentication. - `BEARER` - OAuth2 Bearer Token. - UpdateWebhookEnableDisable - `enabled` boolean — Enable or disable the `Webhook`. Disabled webhooks will not receive events. - `true` - webhook events are sent to the `url`. - `false` - webhook events are not sent to the `url`. - UpdateWebhookEventFiltering - `enabled_events` object[] — A list of webhook events to enable for API entities. There can be only one enabled event object per `entity`. This list is optional and overrides default webhook events. See [Webhook Events](/additional-resources/developers/webhooks/webhook-events) to learn which events are automatically subscribed at creation. When included in a PUT request, this list replaces all previously configured events. - `entity` string — The API entity for which you want to receive webhook events. - `types` string[] — A list of webhook event types you want to receive for the specified `entity`. See the [Webhook Events](/additional-resources/developers/webhooks/webhook-events) guide to learn which values are accepted for each entity. ## Response `200` A single `Webhook` - Webhook - `id` string — The ID of the resource. - `created_at` string, date-time — Timestamp of when the object was created. - `updated_at` string, date-time — Timestamp of when the object was last updated. - `application` string — ID of the `Application` the resource was created under. - `authentication` object — Credentials included in webhook POST requests so your server can confirm each request originated from Finix. To learn about the different authentication methods, see [Managing Webhooks via API](/additional-resources/developers/webhooks/integrating-into-webhooks#managing-webhooks-via-api). - `type` 'NONE' | 'BASIC' | 'BEARER' — The type of authentication the `Webhook` will use: - `NONE`: No authentication will be used. - `BASIC`: Basic authentication. - `BEARER`: OAuth2 Bearer Token. - `enabled` boolean — Whether the `Webhook` is enabled. Disabled webhooks will not receive events. - `true`: Events are sent to the `url`. - `false`: Events are not sent to the `url`. - `enabled_events` object[] — A list of webhook events to enable for API entities. There can be only one enabled event object per `entity`. This list is optional and overrides default webhook events. See [Webhook Events](/additional-resources/developers/webhooks/webhook-events) to learn which events are automatically subscribed at creation. When included in a PUT request, this list replaces all previously configured events. - `entity` string — The API entity for which you want to receive webhook events. - `types` string[] — A list of webhook event types you want to receive for the specified `entity`. See the [Webhook Events](/additional-resources/developers/webhooks/webhook-events) guide to learn which values are accepted for each entity. - `is_accepting_events` boolean — Whether the `Webhook` is currently accepting events; this field mirrors the `enabled` field. - `nickname` string — A human-readable name for the `Webhook`. - `previous_secret_expires_at` string, nullable — The time when the previous `secret_signing_key` expires. Set when the signing key is rotated; `null` on initial creation. - `secret_signing_key` string, nullable — Use this key to verify the `Finix-Signature` header on incoming webhook events, confirming the payload came from Finix, was not tampered with, and was sent recently. For details, see [Verifying Webhook Signatures](/additional-resources/developers/webhooks/integrating-into-webhooks#verifying-webhook-signatures-finix-signature). - `url` string — The HTTP or HTTPS URL to receive events. When an event occurs, Finix sends a POST request to this URL with the webhook event payload. - `_links` object — For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these `_links` to make your follow-up requests and quickly access relevant IDs. - `application` ApplicationLink — Link to the `Application` the request was made under. - `href` string - `self` Self — Link to the resource that was used in the request. - `href` string ## Other responses - `400` — Bad Request. The server cannot process the request due to malformed syntax or invalid data. - `401` — Unauthorized. Authentication is required and has failed or has not been provided. - `403` — Forbidden. The client is authenticated but does not have permission to access the resource. - `404` — Not Found. The requested resource could not be found on the server. - `406` — Not Acceptable. The server could not accept the submitted request. Confirm how the request was formatted and submitted. --- [API](https://skmtc.net/finix/apis/finix-api-reference.md) · [All operations](https://skmtc.net/finix/apis/finix-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/finix/finix-api-reference/versions/5426f6f99c52/schema)