Rotate a webhook endpoint signing secret

curl --request POST \
  --url https://api.checkfu.com/v1/webhook-endpoints/{id}/rotate-secret \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'checkfu-version: <checkfu-version>' \
  --header 'idempotency-key: <idempotency-key>' \
  --data '
{
  "expected_version": 1
}
'

import requests

url = "https://api.checkfu.com/v1/webhook-endpoints/{id}/rotate-secret"

payload = { "expected_version": 1 }
headers = {
    "checkfu-version": "<checkfu-version>",
    "idempotency-key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'checkfu-version': '<checkfu-version>',
    'idempotency-key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({expected_version: 1})
};

fetch('https://api.checkfu.com/v1/webhook-endpoints/{id}/rotate-secret', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.checkfu.com/v1/webhook-endpoints/{id}/rotate-secret",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'expected_version' => 1
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "checkfu-version: <checkfu-version>",
    "idempotency-key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.checkfu.com/v1/webhook-endpoints/{id}/rotate-secret"

	payload := strings.NewReader("{\n  \"expected_version\": 1\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("checkfu-version", "<checkfu-version>")
	req.Header.Add("idempotency-key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.checkfu.com/v1/webhook-endpoints/{id}/rotate-secret")
  .header("checkfu-version", "<checkfu-version>")
  .header("idempotency-key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"expected_version\": 1\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.checkfu.com/v1/webhook-endpoints/{id}/rotate-secret")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["checkfu-version"] = '<checkfu-version>'
request["idempotency-key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"expected_version\": 1\n}"

response = http.request(request)
puts response.read_body

{
  "webhook_endpoint": {
    "id": "<string>",
    "workspace_id": "<string>",
    "url": "<string>",
    "event_types": {},
    "status": "active",
    "disabled_reason": "delivery_failures",
    "consecutive_failures": 1,
    "last_success_at": "<string>",
    "last_failure_at": "<string>",
    "version": 1,
    "created_at": "<string>",
    "updated_at": "<string>"
  },
  "secret": "<string>"
}

{
  "error": {
    "type": "validation.malformed",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-malformed"
  }
}

{
  "error": {
    "type": "auth.invalid_key",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#auth-invalid-key"
  }
}

{
  "error": {
    "type": "auth.disabled_tenancy",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#auth-disabled-tenancy"
  }
}

{
  "error": {
    "type": "validation.not_found",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-not-found"
  }
}

{
  "error": {
    "type": "validation.conflict",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-conflict"
  }
}

{
  "error": {
    "type": "budget.exceeded",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#budget-exceeded"
  }
}

{
  "error": {
    "type": "runtime.internal",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#runtime-internal"
  }
}

Rotate a webhook endpoint signing secret

Mint a new whsec_ signing secret only when expected_version matches the operator-reviewed live endpoint, then shred the old one. There is no overlap window, so deliveries a consumer verifies with the previous secret stop verifying immediately — deploy the new secret alongside the rotation. Requires a non-empty Idempotency-Key; the version fence participates in the request fingerprint, and the returned secret appears exactly once and only an exact keyed retry replays it while this generation is live.

Checkfu support posture: alpha; hosted. Required evidence journey: webhook-delivery. Deployment-specific readiness and the latest proven release are available from GET /v1/support/capabilities.

POST

webhook-endpoints

{id}

rotate-secret

Rotate a webhook endpoint signing secret

curl --request POST \
  --url https://api.checkfu.com/v1/webhook-endpoints/{id}/rotate-secret \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'checkfu-version: <checkfu-version>' \
  --header 'idempotency-key: <idempotency-key>' \
  --data '
{
  "expected_version": 1
}
'

import requests

url = "https://api.checkfu.com/v1/webhook-endpoints/{id}/rotate-secret"

payload = { "expected_version": 1 }
headers = {
    "checkfu-version": "<checkfu-version>",
    "idempotency-key": "<idempotency-key>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'checkfu-version': '<checkfu-version>',
    'idempotency-key': '<idempotency-key>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({expected_version: 1})
};

fetch('https://api.checkfu.com/v1/webhook-endpoints/{id}/rotate-secret', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.checkfu.com/v1/webhook-endpoints/{id}/rotate-secret",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'expected_version' => 1
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "checkfu-version: <checkfu-version>",
    "idempotency-key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.checkfu.com/v1/webhook-endpoints/{id}/rotate-secret"

	payload := strings.NewReader("{\n  \"expected_version\": 1\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("checkfu-version", "<checkfu-version>")
	req.Header.Add("idempotency-key", "<idempotency-key>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.checkfu.com/v1/webhook-endpoints/{id}/rotate-secret")
  .header("checkfu-version", "<checkfu-version>")
  .header("idempotency-key", "<idempotency-key>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"expected_version\": 1\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.checkfu.com/v1/webhook-endpoints/{id}/rotate-secret")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["checkfu-version"] = '<checkfu-version>'
request["idempotency-key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"expected_version\": 1\n}"

response = http.request(request)
puts response.read_body

{
  "webhook_endpoint": {
    "id": "<string>",
    "workspace_id": "<string>",
    "url": "<string>",
    "event_types": {},
    "status": "active",
    "disabled_reason": "delivery_failures",
    "consecutive_failures": 1,
    "last_success_at": "<string>",
    "last_failure_at": "<string>",
    "version": 1,
    "created_at": "<string>",
    "updated_at": "<string>"
  },
  "secret": "<string>"
}

{
  "error": {
    "type": "validation.malformed",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-malformed"
  }
}

{
  "error": {
    "type": "auth.invalid_key",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#auth-invalid-key"
  }
}

{
  "error": {
    "type": "auth.disabled_tenancy",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#auth-disabled-tenancy"
  }
}

{
  "error": {
    "type": "validation.not_found",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-not-found"
  }
}

{
  "error": {
    "type": "validation.conflict",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#validation-conflict"
  }
}

{
  "error": {
    "type": "budget.exceeded",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#budget-exceeded"
  }
}

{
  "error": {
    "type": "runtime.internal",
    "message": "<string>",
    "more": "https://docs.checkfu.com/reference/errors#runtime-internal"
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

checkfu-version

enum<string>

required

Available options:

2026-08-27

idempotency-key

string

required

Required string length: 1 - 255

Path Parameters

string

required

Pattern: ^whe_[0-9a-f]{32}$

Body

application/json

expected_version

integer

required

Required range: x > 0

Response

Success

webhook_endpoint

object

required

Show child attributes

secret

string

required

Pattern: ^whsec_[A-Za-z0-9_-]{43}$

Developer tools

Canonical tables

Author protocols

Generated HTTP API

Rotate a webhook endpoint signing secret

Authorizations

Headers

Path Parameters

Body

Response