Rotate a webhook endpoint's secret

POST

/v1/webhook_endpoints/{id}/rotate_secret

const url = 'https://api.example.com/v1/webhook_endpoints/example/rotate_secret';
const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.example.com/v1/webhook_endpoints/example/rotate_secret \
  --header 'Authorization: Bearer <token>'

Issues a new signing secret, returned on this response only. For 24 hours deliveries carry a signature made with each, so your receiver can switch over without dropping an event.

Authorizations

AccessToken

Parameters

Path Parameters

required

string

The object’s id.

Responses

200

The endpoint, with its new secret.

application/json

object

string

object

string

Allowed value: webhook_endpoint

url

string format: uri

enabled_events

Array<string>

status

string

Allowed values: enabled disabled

secret

The signing secret, whsec_.... Returned on create and rotate only.

string

livemode

boolean

created

A Unix timestamp.

integer

Example

{
  "id": "we_3f9a1c2b7d4e5f60718293a4",
  "object": "webhook_endpoint",
  "status": "enabled"
}

401

authentication_failure: access_token_required when no token was sent, invalid_access_token when it is not valid, has expired, or is a client secret. Sent with a WWW-Authenticate: Bearer header, which adds error="invalid_token" when a token was sent.

application/json

object

error

required

object

type

required

string

Allowed values: validation_failure authentication_failure authorization_failure not_found conflict timeout_or_in_progress policy_rejection invariant_violation rate_limited dependency_failure

code

required

A stable name for this refusal. Branch on this, never on message.

string

message

required

For the developer reading a log. May be reworded.

string

param

required

The field or parameter at fault, when there is one.

string | null

request_id

required

string | null

Example

{
  "error": {
    "type": "validation_failure"
  }
}

403

authorization_failure with merchant_mismatch: a Merchant-Id header, query parameter or body field names a merchant or tenant other than the key’s.

application/json

object

error

required

object

type

required

string

Allowed values: validation_failure authentication_failure authorization_failure not_found conflict timeout_or_in_progress policy_rejection invariant_violation rate_limited dependency_failure

code

required

A stable name for this refusal. Branch on this, never on message.

string

message

required

For the developer reading a log. May be reworded.

string

param

required

The field or parameter at fault, when there is one.

string | null

request_id

required

string | null

Example

{
  "error": {
    "type": "validation_failure"
  }
}

404

not_found: resource_missing for an id this key cannot see, route_missing for a path that does not exist.

application/json

object

error

required

object

type

required

string

Allowed values: validation_failure authentication_failure authorization_failure not_found conflict timeout_or_in_progress policy_rejection invariant_violation rate_limited dependency_failure

code

required

A stable name for this refusal. Branch on this, never on message.

string

message

required

For the developer reading a log. May be reworded.

string

param

required

The field or parameter at fault, when there is one.

string | null

request_id

required

string | null

Example

{
  "error": {
    "type": "validation_failure"
  }
}

503

dependency_failure with service_unavailable: something on our side did not answer, or failed part-way. Whether the secret was rotated is not known, and a new secret is shown only in the answer you did not get. This call takes no Idempotency-Key: send it again, and it rotates again, so use the secret in the answer you receive. A secret the unanswered call made, or the one before it, keeps signing for 24 hours and then stops.

application/json

object

error

required

object

type

required

string

Allowed values: validation_failure authentication_failure authorization_failure not_found conflict timeout_or_in_progress policy_rejection invariant_violation rate_limited dependency_failure

code

required

A stable name for this refusal. Branch on this, never on message.

string

message

required

For the developer reading a log. May be reworded.

string

param

required

The field or parameter at fault, when there is one.

string | null

request_id

required

string | null

Example

{
  "error": {
    "type": "validation_failure"
  }
}