Rotate the webhook signing secret

Issues a new signing secret and returns it, in this response only. The replaced secret keeps verifying for another 24 hours unless expireNow is set, so a receiver can accept both while it swaps over. Webhooks declared in a tenant manifest rotate here too, since a manifest never carries a secret.

POST /v1/webhooks/{webhookId}/rotate

Authorization

• Authorization Bearer token · header required

Authorization: Bearer <token> with an API key (sfa_ prefix), an OAuth access token, a session token, or a Space machine credential (sfm_ prefix).

• Authorization OAuth2 access token · header required

OAuth 2.0 with Spacefast scopes. People use the authorization code flow; machines use client credentials.

Scopes: spaces:write

Path parameters

• webhookId string required

min length 1

Request body

• required application/json

• expireNow boolean

Reject the previous secret immediately instead of accepting it for another 24 hours.

default: false

Responses

200 Response for status 200

• data object required

Show properties Hide properties

• id string required
  • url string required
  • events string[] required

Event filters this webhook is subscribed to.

• status string required

active delivers. failing follows 8 consecutive failures and still delivers. disabled follows 32 and stops. deleted is kept for audit only. Any success resets the count.

Allowed: active disabled failing deleted

• secret string

  Signing secret, present only in the response that created the webhook or rotated its secret. Store it then; it cannot be read back.

• secretPreview string required

  First eight and last four characters of the current signing secret.

• previousSecretExpiresAt string | any required

ISO 8601 timestamp when the secret replaced by the last rotation stops being accepted. Null when no earlier secret is still valid.

Show properties Hide properties

Any of:

• string
• createdAt string required
• updatedAt string required

200 default

{
  "$schema": "http://example.com",
  "data": {
    "id": "string",
    "url": "http://example.com",
    "events": [
      "string"
    ],
    "status": "active",
    "secret": "string",
    "secretPreview": "string",
    "previousSecretExpiresAt": "2019-08-24T14:15:22Z",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  }
}

Error Response Structure

{
  "$schema": "http://example.com",
  "type": "string",
  "title": "string",
  "status": -9007199254740991,
  "detail": "string",
  "code": "string",
  "pointer": "string",
  "details": {
    "property1": null,
    "property2": null
  },
  "suggestions": [
    "string"
  ],
  "next": [
    "string"
  ],
  "requestId": "string"
}

Try it

Server

Base URL https://api.spacefast.com

Custom base URL Overrides the selected server when set.

Authorization

Bearer token

Remember on this device

Include my values in samples

Parameters

• webhookId path*

Body application/json

• expireNow boolean Reject the previous secret immediately instead of accepting it for another 24 hours.

Request Examples

cURL

curl -X POST "https://api.spacefast.com/v1/webhooks/string/rotate" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "expireNow": false
}'

JavaScript

const response = await fetch("https://api.spacefast.com/v1/webhooks/string/rotate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"expireNow\": false\n}"
});

Python

import requests

response = requests.post(
    "https://api.spacefast.com/v1/webhooks/string/rotate",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Content-Type": "application/json"
    },
    data="{\n  \"expireNow\": false\n}",
)

Response Example

200 default