Create or rotate the status callback secret

The signing secret for status_callback requests (POST /v1/messages), returned once.

POST/v1/webhooks/callback_secret

Details

The first call creates it (201); a later call replaces it (200) and the old secret keeps signing for 24 hours, as a second v1= in the signature header. Callbacks are signed exactly like webhook endpoints (textkit-signature).

Recorded in the audit log as webhook.secret_rotated. Scope: webhooks:write.

Responses

200CallbackSecret
Rotated
201CallbackSecret
Created
401Error
Missing, malformed, or revoked API key
402Error
Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged
429Error
Rate limit or quota exceeded

Response Fields (200)

objectcallback_secret
secretstring
Example: whsec_a1B2c3D4e5F6g7H8a1B2c3D4e5F6g7H8.
previous_secret_expires_atstring (date-time)
When the replaced secret stops signing; null on the first call. Nullable.

Errors

Every error has the same JSON shape, and request_id matches the X-Request-Id response header. Errors lists every code and what to do about it.

401
Missing, malformed, or revoked API key
402
Billable live calls only: the prepaid credit balance cannot cover the call (insufficient_credits); nothing was done or charged
429
Rate limit or quota exceeded

const res = await fetch('https://api.jointextkit.com/v1/webhooks/callback_secret', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TEXTKIT_API_KEY}`,
  },
});

if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();

Response 200

{
  "object": "callback_secret",
  "secret": "whsec_a1B2c3D4e5F6g7H8a1B2c3D4e5F6g7H8"
}