Get or rotate the webhook signing secret

POST/tenant/webhook-secret/rotateProbar

ServidorURL base

API key x-api-keyRecordar la clave en este navegador (localStorage, no sale de aquí)

CabecerasIdempotency-KeyÚnico por operación. El alcance es tu cuenta **y el modo** de la key: una `sk_test_` y una `sk_live_` no comparten keys. Dura 24 h. Reintentar con la misma key y payload devuelve la respuesta original, con el mismo código HTTP y la cabecera `Idempotent-Replayed: true`; con otro payload da `409 idempotency_key_reused`. Los campos secretos (el `url` de una gift card, una `apiKey` nueva, un `webhookSecret`) sólo llegan en la primera respuesta: al repetir llegan en `null`.

La llamada la hace tu navegador, contra el servidor que elijas arriba. Si la documentación no está servida desde el mismo origen que la API, el navegador puede bloquear la respuesta por CORS: en ese caso abre estas páginas desde la propia API (/docs) o usa el curl de arriba.

POST

/tenant/webhook-secret/rotate

const url = 'http://localhost:3000/v1/tenant/webhook-secret/rotate';
const options = {method: 'POST', headers: {'x-api-key': '<x-api-key>'}};

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

curl --request POST \
  --url http://localhost:3000/v1/tenant/webhook-secret/rotate \
  --header 'x-api-key: <x-api-key>'

Generates a new whsec_ and returns it only once. It is also how you get it if your key arrived by link (delivery by link doesn’t include the secret). Scope tenant:write.

The previous secret stops working immediately: events sent from then on, retries included, are signed with the new one. Update your receiver before rotating, or accept both signatures during the switch.

In a production account the secret also signs live traffic: rotate it with an sk_live_ key. With an sk_test_ it returns 403 insufficient_scope. In a test account it works with your sk_test_.

If you send Idempotency-Key and repeat the call, the repeated response has webhookSecret: null: the secret isn’t stored.

Authorizations

ApiKeyAuth

Parameters

Header Parameters

Idempotency-Key

string

Único por operación. El alcance es tu cuenta y el modo de la key: una sk_test_ y una sk_live_ no comparten keys. Dura 24 h. Reintentar con la misma key y payload devuelve la respuesta original, con el mismo código HTTP y la cabecera Idempotent-Replayed: true; con otro payload da 409 idempotency_key_reused. Los campos secretos (el url de una gift card, una apiKey nueva, un webhookSecret) sólo llegan en la primera respuesta: al repetir llegan en null.

Responses

201

Secreto nuevo. Guárdalo ahora; no se vuelve a mostrar.

application/json

object

webhookSecret

whsec_ + 48 hex. null sólo en una repetición con la misma Idempotency-Key.

string

nullable

warning

string

Example

{
  "webhookSecret": "whsec_<48 caracteres hexadecimales>",
  "warning": "Úsalo para verificar la firma (x-signature = HMAC-SHA256 de `timestamp.body`)."
}

403

insufficient_scope: la key no tiene tenant:write, o es una sk_test_ de una cuenta real (el secreto firma también lo live; usa una key sk_live_).

application/json

object

error

object

meta

Contexto estructurado del error cuando lo hay: qué límite se superó y de cuánto, qué campo es inválido, cuánto saldo había. No aparece en errores internos.

object

key

additional properties

any

type

string

Allowed values: invalid_request_error authentication_error rate_limit_error upstream_error api_error

code

Código ESTABLE. Programa contra esto.

string

message

string

request_id

string

Example

{
  "error": {
    "type": "invalid_request_error",
    "code": "insufficient_balance",
    "request_id": "req_8a0312ba896772bc441134cd"
  }
}