ManagementExperimental

Rotate a webhook endpoint's signing secret

Replaces the endpoint's signing secret and returns the new one, the only time it is shown. The new secret signs the next attempt to the endpoint, retries included, so update the consumer straight away if it verifies signatures; deliveries it rejects in the meantime are retried.

post/management/webhooks/{webhookEndpointReference}/rotate-secret

Authorization

Authorization: Bearer {token} — an OAuth2 access token from the client-credentials flow. How authentication works

Path parameters

webhookEndpointReferencestringrequired

Webhook endpoint reference, as returned by GET /management/webhooks.

Responses

200The endpoint, with its new signing secretapplication/json

Show response body

dataobject

Show properties

webhookEndpointReferencestring

Identifies the endpoint in GET /management/webhooks/{webhookEndpointReference}/deliveries.

urlstring · uri

Destination Firsty posts events to.

eventTypesarray of string

Event types delivered to this endpoint. Values this client subscribed to before an event type was retired are returned as stored, so an entry may be absent from GET /catalog/webhook-event-types.

descriptionstring | null

Free-text label for the endpoint.

activeboolean

Whether events are delivered to this endpoint.

createdAtstring · date-time

updatedAtstring · date-time

signingSecretstring

Key that signs every delivery to this endpoint: whsec_ followed by base64. The HMAC key is the base64-decoded bytes after the prefix. Returned only by create and rotate-secret.

401Unauthorized - missing or invalid API key 404Resource not found 429Rate limit exceeded. A `429` can also arrive without these headers or this body; handle it by its status code.500Internal server error

Request

curl 'https://connect.firsty.app/api/v3/management/webhooks/{webhookEndpointReference}/rotate-secret' \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

fetch('https://connect.firsty.app/api/v3/management/webhooks/{webhookEndpointReference}/rotate-secret', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN'
  }
})

requests.post(
    "https://connect.firsty.app/api/v3/management/webhooks/{webhookEndpointReference}/rotate-secret",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    }
)

$client = new GuzzleHttp\Client();

$response = $client->request('POST', 'https://connect.firsty.app/api/v3/management/webhooks/{webhookEndpointReference}/rotate-secret', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN'
  ]
]);

package main

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

func main() {
	requestUrl := "https://connect.firsty.app/api/v3/management/webhooks/{webhookEndpointReference}/rotate-secret"

	req, _ := http.NewRequest("POST", requestUrl, nil)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")

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

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

	fmt.Println(res)
	fmt.Println(string(body))

}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://connect.firsty.app/api/v3/management/webhooks/{webhookEndpointReference}/rotate-secret"))
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .method("POST", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

curl 'https://connect.test.firsty.app/api/v3/management/webhooks/{webhookEndpointReference}/rotate-secret' \
  --request POST \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

fetch('https://connect.test.firsty.app/api/v3/management/webhooks/{webhookEndpointReference}/rotate-secret', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_ACCESS_TOKEN'
  }
})

requests.post(
    "https://connect.test.firsty.app/api/v3/management/webhooks/{webhookEndpointReference}/rotate-secret",
    headers={
      "Authorization": "Bearer YOUR_ACCESS_TOKEN"
    }
)

$client = new GuzzleHttp\Client();

$response = $client->request('POST', 'https://connect.test.firsty.app/api/v3/management/webhooks/{webhookEndpointReference}/rotate-secret', [
  'headers' => [
    'Authorization' => 'Bearer YOUR_ACCESS_TOKEN'
  ]
]);

package main

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

func main() {
	requestUrl := "https://connect.test.firsty.app/api/v3/management/webhooks/{webhookEndpointReference}/rotate-secret"

	req, _ := http.NewRequest("POST", requestUrl, nil)

	req.Header.Add("Authorization", "Bearer YOUR_ACCESS_TOKEN")

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

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

	fmt.Println(res)
	fmt.Println(string(body))

}

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://connect.test.firsty.app/api/v3/management/webhooks/{webhookEndpointReference}/rotate-secret"))
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .method("POST", HttpRequest.BodyPublishers.noBody())
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Response

{
  "data": {
    "webhookEndpointReference": "K7Q2M9XA",
    "url": "https://partner.example.com/firsty/webhooks",
    "eventTypes": [
      "package.created",
      "package.usage.threshold"
    ],
    "description": "Production",
    "active": true,
    "createdAt": "2026-01-15T09:30:00Z",
    "updatedAt": "2026-01-15T09:30:00Z",
    "signingSecret": "whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"
  }
}

{
  "type": "https://developers.firsty.app/errors/unauthorized",
  "code": "unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or missing bearer token"
}