Webhooks

Um webhook avisa os seus próprios sistemas sobre o que acontece em um espaço de trabalho: aprovações, episódios novos, vídeos prontos, posts publicados e mais. O ShowBits envia cada evento assinado para o seu endereço. Os webhooks fazem parte dos planos Enterprise e OnPremise; em todos os planos, as conexões para n8n, Zapier e Make têm webhooks próprios.

Quem configura
Administradores do espaço de trabalho
Planos
Enterprise e OnPremise
O que o ShowBits envia
Eventos assinados que identificam os objetos pelo ID, sem nomes, títulos ou textos

Adicionar um webhook

Os administradores do espaço de trabalho adicionam os webhooks. O seu sistema precisa de um endereço que aceite requisições POST via https e seja acessível pela internet.

  1. Abra Settings → API.
  2. Em Webhooks, clique em Add webhook.
  3. Digite o endereço do seu sistema em Address (https). Ele precisa começar com https://, não pode conter nome de usuário nem senha e precisa ser acessível pela internet.
  4. Se quiser, digite uma descrição em Description, por exemplo o nome do sistema.
  5. Em Events, marque os eventos de que o seu sistema precisa. A caixa de um grupo, como Clips, marca todos os eventos dele.
  6. Clique em Add.
  7. Clique em Copy e guarde o segredo no seu sistema. O ShowBits o exibe somente esta vez.
  8. Clique em Done.

Um espaço de trabalho tem no máximo 10 webhooks, contando os das conexões para n8n, Zapier e Make. No n8n, use a Production URL do nó Webhook; a caixa de diálogo avisa quando você digita a URL de teste dele.

Captura de tela do ShowBits: Adicionar um webhook

Eventos e o seu conteúdo

Os eventos estão nos grupos Clips, Episodes, Posts, Quote cards, Team, Integrations, Brand kits e Workspace. Por exemplo: clip.approved quando um clipe é liberado, clip.forwarded quando ele passa para a etapa de aprovação seguinte, clip.video_ready quando o vídeo dele fica pronto, episode.analysed, episode.embargo_ended, post.published, post.failed e clip.delivered para uma entrega no seu MAM ou DAM.

Cada evento é um POST com corpo em JSON: id (o ID do evento), type, occurredAt, workspace (ID e slug), object (tipo e ID do episódio, do clipe ou do post), via (app, api, automation ou system) e data, com alguns campos inofensivos, como canal ou horário. Nomes, títulos e textos nunca fazem parte dele; o seu sistema busca os detalhes pela API REST.

Verificar a assinatura

Cada evento traz os cabeçalhos ShowBits-Event (o tipo do evento), ShowBits-Delivery (o ID da entrega) e ShowBits-Signature: t=…,v1=…. Verifique a assinatura antes que o seu sistema reaja a um evento.

  1. Leia o corpo da requisição como texto bruto, antes que o seu sistema interprete o JSON.
  2. Em ShowBits-Signature, pegue t, o horário em segundos Unix, e todos os valores v1.
  3. Calcule um HMAC-SHA256 sobre t, um ponto e o corpo bruto, com o segredo inteiro como chave, incluindo whsec_, e escreva o resultado em hexadecimal.
  4. Aceite o evento somente se o resultado corresponder a um dos valores v1; compare em tempo constante.
  5. Descarte o evento se t tiver mais de cinco minutos.

Durante um dia após a criação de um novo segredo, o cabeçalho traz um segundo v1, assinado com o segredo anterior. Há código de exemplo na documentação da API.

Testar, pausar e verificar entregas

Cada webhook mostra o host, o status (Active, Paused ou Paused after failures), a descrição, o número de eventos e quando o endereço aceitou um evento pela última vez.

  1. Clique em Test para enviar um evento de teste (webhook.test). Ele também é enviado a um webhook pausado.
  2. Clique em Deliveries para ver os últimos 20 eventos com o resultado de cada um: aceito (com o código de status), em nova tentativa (com o número de tentativas e o erro) ou abandonado (com o erro).
  3. Clique em Pause para parar de enviar eventos e em Resume para retomar.

Eventos que ocorrem enquanto um webhook está pausado não são enviados depois.

Captura de tela do ShowBits: Testar, pausar e verificar entregas

Criar um novo segredo

Crie um novo segredo se o antigo puder ter se tornado conhecido, ou para trocá-lo de tempos em tempos. O segredo anterior continua assinando também por um dia, para que você possa migrar o seu sistema sem interrupção.

  1. Clique em New secret no webhook.
  2. Confirme com New secret.
  3. Clique em Copy e guarde o novo segredo no seu sistema.
  4. Clique em Done.

Excluir um webhook

Excluir um webhook o encerra definitivamente: nenhum evento é mais enviado para lá, e as entregas pendentes são descartadas.

  1. Clique no ícone da lixeira (Delete) no webhook.
  2. Confirme com Delete.

Novas tentativas, pausa automática e eventos repetidos

O seu endereço precisa responder com um status de 200 a 299 em até 10 segundos; o ShowBits não segue redirecionamentos. Caso contrário, o ShowBits tenta de novo após 1 minuto, 5 minutos, 30 minutos, 2 horas, 6 horas e 24 horas e, depois disso, desiste daquele evento. Se o endereço não aceitar nada durante três dias, o ShowBits pausa o webhook (Paused after failures) e envia um e-mail aos administradores do espaço de trabalho. Corrija o problema no endereço e depois clique em Resume.

Um evento pode chegar mais de uma vez: após uma nova tentativa ou em dois webhooks com o mesmo endereço. Reconheça as repetições pelo id: ele é o mesmo em todas as tentativas e em todos os webhooks.

Perguntas

O endereço pode estar na nossa rede interna?

Não. O ShowBits só envia para endereços https acessíveis pela internet, sem nome de usuário e senha.

Por que um evento não traz o título do clipe?

Os eventos identificam os objetos apenas pelo ID; assim, nenhum nome, título ou texto sai do ShowBits por esse caminho. Com um token, o seu sistema busca os detalhes pela API REST.

Por quanto tempo as entregas ficam guardadas?

30 dias. Deliveries mostra as últimas 20 de um webhook.

O nosso sistema pode gerenciar os próprios webhooks?

Sim, pela API REST, com um token que tenha as permissões webhooks:read e webhooks:write. A pessoa a quem o token pertence precisa ter a função de administrador no espaço de trabalho.

Estamos no Creator ou no Business. Podemos receber eventos?

Os webhooks em Settings → API fazem parte do Enterprise e do OnPremise. Em todos os planos, as conexões para n8n, Zapier e Make têm webhooks próprios, com a mesma assinatura: veja n8n, Zapier e Make.