O que é um webhook?
Um webhook permite que você seja notificado quando determinadas ações do sistema ocorrem, por meio de uma chamada a uma URL fornecida por você. Webhooks também são conhecidos como “URL Callbacks” ou “HTTP push calls”. Sua URL deve usar SSL e começar com HTTPS.Ações de webhook
Veja as ações disponíveis para webhooks.
Entendendo os webhooks do Ayrshare
Os webhooks são categorizados pela ação específica e são registrados no nível do Primary Profile ou do User Profile. Quaisquer atualizações do Primary Profile ou dos User Profiles são enviadas primeiro para o webhook registrado do User Profile. Se o User Profile não tiver um webhook registrado, a atualização será enviada para o webhook registrado do Primary Profile. Por exemplo:- Se um User Profile tiver um webhook Social Action registrado e desvincular o TikTok, a URL do webhook Social Action registrado para o User Profile será chamada. O webhook do Primary Profile não será chamado.
- Se um User Profile desvincular o TikTok e não tiver um webhook Social Action registrado, mas o Primary Profile tiver um webhook registrado, a URL do webhook Social Action registrado para o Primary Profile será chamada.
Registrar um webhook
Registre um webhook fornecendo uma URL de endpoint e o tipo de ação para o endpoint POST/hook/webhook. Quando a ação ocorrer, uma mensagem HTTP POST será enviada para a URL fornecida.
Por exemplo, registre uma URL para ser notificado sobre o status de uma publicação agendada.
A URL do endpoint do webhook não deve utilizar redirecionamentos e precisa ser a URL de destino final.
Se você registrar apenas o webhook do Primary Profile, os User Profiles herdarão automaticamente o webhook do Primary Profile.
Para ter um webhook exclusivo para cada User Profile, você precisa registrar um webhook para cada User Profile.
Depois que seu webhook receber o
HTTP POST, seu servidor deve responder com
um status HTTP 200 para marcar a chamada como bem-sucedida. Se o seu servidor não
responder em 15 segundos, a tentativa será registrada como falha e será feita uma
nova tentativa. Responda assim que receber a requisição e faça o processamento
de forma assíncrona. Um timeout não é uma rejeição, portanto, se o seu handler
concluir o trabalho, mas responder tarde, a nova tentativa fará com que você o processe duas vezes.Novas tentativas de webhook
O fato de uma entrega com falha ser repetida depende de como ela falhou. Cada nova tentativa carrega o mesmohookId. O payload é reconstruído a cada tentativa, portanto timeStamp — e a assinatura sobre ele — podem mudar.
Repetido — falhas transitórias. Uma resposta 429, 408 ou 425, qualquer 5xx, um tempo limite esgotado ou uma conexão interrompida recebe até 9 tentativas de envio ao longo de cerca de uma hora — o primeiro envio mais 8 repetições. Se ainda estiver falhando depois disso, a entrega é tentada novamente em uma programação decrescente — cerca de 5 minutos, 30 minutos, 2 horas e 12 horas depois. Portanto, uma entrega pode chegar até cerca de 16 horas após o evento original.
Não repetido — rejeições. Qualquer outra resposta 4xx, como 400, 401, 403, 404 ou 410, é tratada como final na primeira tentativa. Elas indicam que a própria requisição foi rejeitada, e repeti-la não pode mudar o resultado.
Semântica de entrega e idempotência
O Ayrshare entrega webhooks pelo menos uma vez. Duplicatas ocasionais são operação normal, não um defeito. Todo consumidor precisa de idempotência como uma propriedade permanente. Duplicatas chegam em duas formas diferentes, e cada uma precisa de uma chave diferente:hookId identifica uma entrega de um evento. Ele é idêntico em cada nova tentativa dessa entrega, então reivindicá-lo torna as novas tentativas seguras. Mas uma nova notificação do mesmo evento subjacente chega com um hookId novo, então hookId por si só não reconhecerá esse caso.
Padrão recomendado para o receptor:
- Responda primeiro. Retorne
2xximediatamente e processe de forma assíncrona. Um timeout não é uma rejeição. Se você concluir o trabalho, mas responder tarde, o evento será enviado novamente. - Reivindique
hookIdatomicamente no momento em que a requisição chega. Use uma restrição de unicidade, umINSERT ... ON CONFLICT DO NOTHINGou umSET NX, e não uma verificação do tipo ler-e-escrever. Duas tentativas podem chegar simultaneamente, e uma proteção do tipo verificar-e-agir deixa as duas passarem. - Reivindique também uma chave sua, construída a partir do payload, para que uma segunda notificação carregando um novo
hookIdainda seja reconhecida. Emmessages,idcombinado comsubActionfunciona bem. - Então faça o trabalho, mantendo as duas reivindicações por tempo suficiente para cobrir a janela de novas tentativas e qualquer nova notificação posterior. Como uma nova tentativa pode chegar até cerca de 16 horas depois, mantenha suas reivindicações por pelo menos 24 horas. Uma reivindicação que expira antes disso não reconhecerá uma tentativa tardia, e você processará o mesmo evento duas vezes.
O
id do payload não é único por si só para todo tipo de evento. O mesmo
id de mensagem se repete em edições e reações, e payloads de messageRead não carregam
id, portanto combine-o com subAction em vez de usá-lo isoladamente.Cabeçalhos de metadados de entrega
Cada entrega carrega dois cabeçalhos identificando essa transmissão específica, para que você possa distinguir uma original de uma nova tentativa:X-Ayrshare-Delivery-Attempt é 0 no primeiro envio e é incrementado em um a cada nova tentativa, então qualquer valor acima de 0 significa que já enviamos essa entrega pelo menos uma vez. Trate-o como um contador ilimitado em vez de um conjunto fixo de valores. O número de novas tentativas é um detalhe operacional que pode mudar. X-Ayrshare-Delivery-Id é único para cada tentativa. Cite-o para o suporte, pois ele identifica o registro exato da entrega.
Esses identificam a transmissão; hookId identifica o evento. Deduplique por hookId, não pelo delivery id. O delivery id é diferente em cada tentativa por definição, então nada jamais seria reconhecido como duplicata.
Segurança do webhook
Você pode optar por adicionar segurança adicional definindo autenticação HMAC como uma requisição HTTP. Isso é feito frequentemente para evitar ataques de replay. O Ayrshare usa HMAC-SHA256 para gerar o hash do corpo da mensagem e o inclui, junto com o timestamp UNIX, no cabeçalho do POST.X-Authorization-Content-SHA256 com o HMAC-SHA256 do corpo do POST. A chave secreta de assinatura é por profile. Uma chave secreta por User Profile, usada em todas as ações de webhook daquele profile, de forma que defini-la para uma ação a altera para todas as ações daquele profile. Contas com múltiplos profiles gerenciam uma chave secreta separada por profile (mire em um profile com o cabeçalho Profile-Key).