Webhooks
Rotacionar chave secreta de assinatura
Rotacione com segurança a chave secreta de assinatura do seu webhook com uma janela de tolerância de assinatura dupla de 24 horas
POST
Visão geral
O Ayrshare assina cada entrega de webhook com um HMAC-SHA256 do payload, tendo como chave sua chave secreta de assinatura, para que seu receptor possa confirmar que a entrega realmente veio do Ayrshare. Consulte Segurança do webhook para entender como a verificação funciona. Rotacionar sua chave secreta de assinatura permite substituí-la em uma programação regular, ou imediatamente se você suspeitar que ela foi exposta. Para tornar a rotação segura, o Ayrshare abre uma janela de tolerância de 24 horas após cada rotação, durante a qual as entregas são assinadas com ambas a sua chave secreta anterior e a nova. Isso permite que você atualize seu receptor no seu próprio ritmo, sem descartar ou rejeitar uma única entrega — o mesmo padrão usado por Stripe e GitHub.A chave secreta de assinatura é por profile: há uma chave secreta por User Profile (UID),
e ela assina todas as ações de webhook que aquele profile tem registradas. Não há
chave secreta de assinatura por ação — definir ou rotacionar a chave secreta a altera para todas as
ações daquele profile ao mesmo tempo.
Rotacionar pelo painel
Você pode definir ou rotacionar sua chave secreta de assinatura na página Webhooks do Painel do Desenvolvedor. O painel Signing Secret aparece acima da sua lista de webhooks assim que o profile tem pelo menos um webhook registrado.1
Abra o painel Signing Secret
Acesse a página Webhooks. Se ainda não houver chave secreta configurada, o painel exibe No signing secret configured com um botão Set Signing Secret. Se já houver uma configurada, ele exibe Signing secret configured com um botão Rotate.
2
Definir ou rotacionar
Clique em Set Signing Secret (primeira vez) ou Rotate (chave secreta existente). Um modal se abre com uma chave secreta forte, gerada aleatoriamente, pré-preenchida e revelada. Você pode Copy (copiar), Regenerate (regerar) uma nova, ou alternar paste my own para fornecer seu próprio valor.
3
Confirmar
Copie a chave secreta para um local seguro — ela é exibida apenas uma vez e nunca mais pode ser recuperada pela interface — e então confirme para enviar. Uma notificação de sucesso aparece e o painel é atualizado.
4
Atualize seu receptor
Em uma rotação (não em uma primeira definição), o painel exibe um indicador da janela de tolerância ativa e o botão Rotate fica desabilitado até que a janela se feche. Você tem 24 horas para implantar a nova chave secreta no seu receptor.
Rotacionar pela API
Rotacione (ou defina) a chave secreta de assinatura com uma única chamada. Isso cria uma nova chave secreta, aponta a referência de chave secreta do profile para ela e — quando uma chave secreta existente já estava em vigor — registra a chave secreta substituída como a chave secreta anterior com expiração em 24 horas.Parâmetros do cabeçalho
Parâmetros do corpo
string
obrigatório
O valor da nova chave secreta de assinatura. Qualquer string não vazia é aceita. Recomendamos um valor aleatório longo e de alta entropia (por exemplo, 32 bytes aleatórios codificados em base64url).
secret em texto claro nunca é retornado na resposta e nunca é registrado em logs. A resposta traz o refId voltado ao cliente (um hash do UID), nunca o UID em si. O cabeçalho Profile-Key é opcional e limita a rotação a um único User Profile para contas com múltiplos profiles.
Um secret ausente ou vazio retorna um erro mapeado (code: 101, “Missing/incorrect parameter”) com status HTTP 400, e nenhuma alteração é feita na sua chave secreta atual. Uma primeira definição pela API (sem chave secreta existente) cria a chave secreta sem chave secreta anterior registrada e sem janela de tolerância.
Procedimento de rotação segura
Por causa da janela de tolerância de 24 horas, não há uma ordem obrigatória de operações — seu receptor continua funcionando durante todo o processo. A sequência recomendada é:1
Rotacione a chave secreta
Rotacione pelo painel ou pela API. O Ayrshare imediatamente começa a assinar as entregas com ambas as suas chaves secretas, a anterior e a nova.
2
Atualize seu receptor
Em até 24 horas, implante a nova chave secreta no seu receptor de webhook para que ele verifique contra o novo valor.
3
Deixe a janela se fechar
Após 24 horas, o Ayrshare limpa automaticamente a chave secreta anterior e assina somente com a nova chave secreta. Nenhuma ação adicional é necessária do seu lado.
Verificando assinaturas durante a janela de tolerância
Fora de uma janela de tolerância, as entregas assinadas carregam os cabeçalhos padrão (consulte Segurança do webhook):X-Authorization-Content-SHA256-V2 lista ambas as assinaturas, a atual primeiro, separadas por vírgula:
X-Authorization-Content-SHA256 permanece inalterado: ele sempre carrega o único
HMAC da chave secreta atual, por compatibilidade retroativa. Assinaturas duplas aparecem apenas no
novo cabeçalho X-Authorization-Content-SHA256-V2.X-Authorization-Content-SHA256-V2 é prefixado com uma tag de esquema. v1= denota uma assinatura HMAC-SHA256, calculada exatamente como X-Authorization-Content-SHA256. O cabeçalho -V2 está sempre presente sempre que uma entrega é assinada — ele carrega ao menos v1=<current-sig> — para que você possa contar com ele como um contrato estável para o receptor.
Para verificar uma entrega durante (ou fora de) uma rotação:
1
Calcule o HMAC
Calcule o HMAC-SHA256 do corpo bruto da requisição usando a chave secreta de assinatura configurada localmente.
2
Compare com cada assinatura listada
Leia
X-Authorization-Content-SHA256-V2, divida-o pelas vírgulas, remova o prefixo v1= de cada valor e aceite a entrega como autêntica se o HMAC calculado corresponder a qualquer assinatura v1= listada.v1=<previous-sig>, enquanto um receptor atualizado para a nova chave secreta corresponde a v1=<current-sig> — ambos têm sucesso durante toda a janela.
Exemplo de verificação no receptor
Node.js
