Um webhook avisa um endereço seu, automaticamente, quando algo acontece no Base. Você pode usá-lo para ser alertado, por exemplo, quando um artigo é promovido ou precisa de revisão.
Quem pode fazer: pessoas com Pode Administrar na organização. Veja Permissões e acessos no Base.
Onde ficam os webhooks
Clique na sua foto (canto superior direito) > Configurações do ambiente > Configurações de Webhooks. A tela lista os webhooks da organização, com as colunas Título, Endpoint e Status.
Como criar um webhook
- Abra Configurações do ambiente > Configurações de Webhooks e clique em Novo Webhook.
- Em Title, dê um nome que explique para que serve o webhook, como "Avisos de artigos".
- Em Endpoint, informe o endereço do seu sistema que vai receber os avisos. Ele precisa aceitar requisições
POST. - Em Eventos, marque os acontecimentos que devem gerar aviso. Você pode marcar mais de um.
- Clique em Testar para enviar um aviso de teste ao endpoint e confira se o seu sistema recebeu.
- Clique em Salvar.
Dica: crie um webhook para cada finalidade, como um para artigos e outro para cursos. Assim fica mais fácil saber de onde vem cada aviso e desligar só o que precisar.
Eventos disponíveis
Hoje, estes são os eventos que disparam um webhook. O nome do evento é o valor que chega no campo event do aviso.
| Evento | Valor em event
|
Quando acontece |
|---|---|---|
| Artigo Promovido | DocsPromoted |
Quando um artigo é promovido. |
| Artigo Removido | DocsRemoved |
Quando um artigo promovido é removido. |
| Curso Promovido | CoursesPromoted |
Quando um curso é promovido. |
| Curso Removido | CoursesRemoved |
Quando um curso promovido é removido. |
| Documento Requer Revisão | DocumentExpired |
Quando um artigo atinge a data de validade e precisa de revisão. |
| Teste | SampleEvent |
Quando você clica em Testar no formulário do webhook. |
Como confirmar que o aviso veio do Base
Quando você cria um webhook, o Base gera um token. Ele é enviado no cabeçalho da requisição HTTP, com o nome X-Webhook-Token. Você pode ver o token nos detalhes do webhook, depois de criá-lo.
Atenção: no seu endpoint, compare o X-Webhook-Token recebido com o token do webhook. Assim, você ignora requisições falsas, enviadas por quem não é o Base.
O que vem no aviso
Todo aviso traz estes campos:
| Campo | O que é |
|---|---|
event |
O nome do evento que disparou o webhook. |
timestamp |
A data em que o evento foi gerado, no formato ISO-8601. |
payload |
O objeto do evento, como um artigo ou um curso. |
Dentro de payload, todos os objetos têm estes campos em comum:
| Campo | O que é |
|---|---|
id |
Identificador único do objeto. |
typename |
O tipo do objeto: Docs (artigos), Courses (cursos) ou Discussions (comentários). |
title |
O título ou nome do objeto. |
content |
O conteúdo do objeto, em HTML. |
slug |
O endereço parcial. Coloque o domínio do seu ambiente na frente para obter o endereço completo. |
authors |
A lista de identificadores dos autores. |
createdAt |
A data de criação, em ISO-8601. |
updatedAt |
A data da última atualização, em ISO-8601. Nem toda atualização é feita por uma pessoa: a plataforma também atualiza objetos por outros motivos. |
promotedAt |
A data da última vez que o objeto foi atualizado por uma pessoa e aprovado por quem aprova, em ISO-8601. |