TextKitDocs

Rotate a webhook signing secret

Replaces the signing secret and returns the new one: the only time the API shows it.

POST/v1/webhooks/{id}/rotate_secret

Path Parameters

  • idstringrequired

    Example: we_a1B2c3D4e5F6.

Body Parameters

The body is optional.

  • expire_previous_ininteger

    Seconds the old secret keeps signing alongside the new one. Default 0. Maximum 604800. Minimum 0. Example: 86400.

Details

With expire_previous_in, the old secret keeps signing for that many seconds (up to 7 days) as a second v1= in the signature header, so you can deploy the new secret without dropping events; every TextKit SDK accepts either. 0 (the default) retires it now. Recorded in the audit log as webhook.secret_rotated.

Scope: webhooks:write.

Responses

  • 200WebhookEndpoint

    The endpoint with its new secret (shown once)

  • 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

  • idstring

    Example: we_a1B2c3D4e5F6.

  • objectwebhook_endpoint
  • urlstring (uri)
  • events* or array of string
  • numbersarray of string

    The number filter: only events about these numbers. Empty: every number.

  • activeboolean
  • modetest, live

    Which events it receives: the mode of the key that created it (or chosen in the console). A key lists and changes only its own mode's endpoints.

  • descriptionstring

    Nullable.

  • created_atstring (date-time)
  • secretstring

    Example: whsec_a1B2c3D4e5F6g7H8a1B2c3D4e5F6g7H8.

  • previous_secret_expires_atstring (date-time)

    When the old secret stops signing; null when it already has. 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