Rotacionar segredo
Gera um novo segredo para a inscrição e invalida o anterior na mesma hora.
apiKeyAuthorizationBearer <token>Chave de API no header Authorization: Bearer <chave de API>.
id*stringid da inscrição, em ULID (26 caracteres).
Segredo rotacionado. Contém o novo secret, exibido só desta vez.
application/json- response
Inscrição com o secret. Só nas respostas de Criar inscrição e Rotacionar segredo.
id*stringIdentificador da inscrição, em ULID.
ownerId*integerId da conta dona da inscrição. Vem da chave de API; não é enviado no corpo.
subscribedEvents*array<>Eventos que a inscrição recebe.
callbackUrl*stringURL que recebe os eventos.
uristatus*WebhookSubscriptionStatusactive: recebe eventos. paused: não recebe; volta com Ativar.
revoked: desligada.
"active""paused""revoked"failureCount*integerTentativas de entrega que falharam desde a última entrega com
sucesso. Conta cada nova tentativa, não cada evento; volta a 0 na
próxima entrega aceita.
lastFailureAt*|Data e hora (ISO 8601, UTC) da última falha de entrega, ou null.
date-timecreatedAt*stringData e hora de criação (ISO 8601, UTC).
date-timeupdatedAt*stringData e hora da última alteração (ISO 8601, UTC).
date-timesecret*stringSegredo da assinatura HMAC-SHA256, em texto puro (43 caracteres, base64url). Aparece só nesta resposta; guarde-o em um cofre de segredos. Se perder, rotacione.
curl -X POST 'https://api.gates2b.com/webhook-subscriptions/string/rotate-secret'{ "id": "01KTQRHR29PZ588RB1YQZWS4A6", "ownerId": 314, "subscribedEvents": [ "charge.paid", "charge.refunded", "payout.paid", "payout.failed" ], "callbackUrl": "https://loja.example.com/webhooks/pagamentos", "status": "active", "failureCount": 0, "lastFailureAt": null, "createdAt": "2026-06-15T14:00:00.000Z", "updatedAt": "2026-06-18T08:00:00.000Z", "secret": "Zt9mQ2v7Lr0xWk4bNc8pHs1yFd6gJu3eTa5oViXqR2M"}O segredo anterior deixa de valer assim que a resposta chega. Entregas assinadas a partir daí, inclusive novas
tentativas de eventos antigos, usam o segredo novo. Guarde o secret da resposta: ele não aparece de novo.
Fluxo
A troca é instantânea do lado da Gates2b: a partir da resposta desta rota, toda entrega sai assinada com o segredo novo. Para não rejeitar nada nesse meio-tempo, faça o seu endpoint aceitar os dois segredos por alguns minutos.
- VocêAceite dois segredosvalide com o atual OU com um segundo, lido de outra variável
- VocêRotacionePOST /rotate-secret; grave o secret da resposta na segunda variável
- Gates2bAssine com o novotoda entrega, inclusive novas tentativas de eventos antigos
- VocêRemova o antigoquando as entregas validarem só com o novo
Na validação com dois segredos, calcule o HMAC com cada um e aceite se qualquer um bater com o v1. O resto da
verificação (janela de 5 minutos, corpo cru, comparação em tempo constante) não muda; veja
Verificar a assinatura.
Rotacione sempre que o segredo puder ter vazado ou quando alguém com acesso a ele sair do time. Se o segredo vazou, rotacione direto, sem o primeiro passo: uma entrega que o seu endpoint rejeitar nesse intervalo volta como nova tentativa, já assinada com o segredo novo.