---
title: "Choose your webhook payload format"
method: PUT
path: "/v2/webhooks/settings"
tags: ["Webhooks"]
---

# Choose your webhook payload format

`PUT /v2/webhooks/settings`

## Request

- Base URL: `https://api.imentiv.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.imentiv.ai/v2/webhooks/settings`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Set the payload format for events created from now on.

`legacy` is the format sent before payload versions existed and is only available to accounts
that already receive it. Events already created keep the format they were created with.

## Request body

- WebhookSettingsUpdate
  - `payload_version` 'legacy' | 'v1', required: The payload format to use for events created from now on. `legacy` can only be kept, not chosen: it is available to accounts that already receive it.

## Response `200`

Successful Response

- WebhookSettings: Your webhook signing secret and payload format. The secret itself is never included.
  - `has_secret` boolean, required: Whether a signing secret exists for your account.
  - `secret_last4` string, nullable: The last four characters of the current secret, to tell secrets apart.
  - `secret_revealed` boolean, required: False until you have read your secret with POST /v2/webhooks/secret. Deliveries are signed from your first event, so read it before you start verifying.
  - `created_at` string, date-time, nullable: When the current secret was created.
  - `previous_secret_expires_at` string, date-time, nullable: After a rotation, until when the previous secret still signs deliveries. While this is in the future each delivery carries two v1 signatures.
  - `payload_version` 'legacy' | 'v1', required: The payload format your webhooks use. `legacy` is the format sent before payload versions existed (UPPERCASE status values, free-text error). `v1` is the documented format.

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-01** `72330e2229c7`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/changes/v2/webhooks/settings/put.md)

---

[API](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai.md) - [All operations](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/llms.txt) - [OpenAPI document](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/revisions/bc15cec7e794?raw)