Skip to main content
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).
O 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.
Se você rotacionar novamente enquanto uma janela de tolerância ainda estiver aberta, a chave secreta recém-substituída torna-se a nova chave secreta anterior e uma nova janela de 24 horas começa. Apenas uma chave secreta anterior é mantida por vez.

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):
Durante a janela de 24 horas após uma rotação, o novo cabeçalho 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.
Cada valor em 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.
Aceitar quando qualquer assinatura listada corresponder é o que torna a rotação sem tempo de inatividade: um receptor ainda configurado com a chave secreta antiga corresponde a 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
Sempre calcule o HMAC sobre os bytes brutos do corpo da requisição, exatamente como recebidos — não sobre um objeto JSON re-serializado. A re-serialização pode alterar espaços em branco ou a ordem das chaves e quebrar a verificação. Use uma comparação em tempo constante (como crypto.timingSafeEqual) para evitar ataques de temporização.
Se o registro da chave secreta atual de uma entrega estiver ausente, a entrega prossegue sem assinatura (sem cabeçalhos de assinatura) em vez de falhar. Se apenas o registro da chave secreta anterior tiver desaparecido, a assinatura anterior é ignorada e a assinatura atual ainda é emitida em ambos os cabeçalhos.