Introdução
Esta documentação descreve como usar os webhooks da Automarticles para automatizar o seu blog. A cada evento de post ou de categoria, a Automarticles envia uma requisição POST com um corpo JSON para a URL que você configurar, e o seu sistema decide o que fazer com ela: criar o post, atualizar, despublicar, apagar.
O nome do evento vem sempre no campo event do corpo. Existem sete: CHECK_INTEGRATION, POST_CREATED, POST_UPDATED, POST_DELETED, CATEGORY_CREATED, CATEGORY_UPDATED e CATEGORY_DELETED.
Autenticação
Toda requisição de webhook leva um token de acesso no cabeçalho access-token. Você encontra esse token na Automarticles, em Configurações › Integrações › Webhook, no campo Token de Autenticação.
No seu endpoint, compare o valor do cabeçalho com o seu token antes de processar qualquer coisa, e recuse (401) a requisição que vier sem ele ou com um valor diferente.
Antes de ativar o envio e começar a receber os eventos, você precisa verificar a integração pelo procedimento a seguir.
2.1Evento CHECK_INTEGRATION
O CHECK_INTEGRATION é o teste inicial: ele confirma que a Automarticles consegue falar com o seu sistema e que o token está sendo reconhecido. O passo a passo:
- Em Configurações › Integrações › Webhook, preencha o campo URL do Webhook com o endereço que vai receber os eventos e salve.
- Clique em Verificar. Enviamos um
POSTpara a sua URL com o token no cabeçalhoaccess-tokene o corpo abaixo. - O seu endpoint precisa responder com status
2xxe um JSON que devolve exatamente o mesmo token recebido. - Com o token devolvido igual ao enviado, a integração fica verificada e você pode ligar a opção Enviar webhooks.
{
"event": "CHECK_INTEGRATION"
}{
"token": "SEU_TOKEN_AQUI"
}Post
A Automarticles envia três eventos de post: POST_CREATED, POST_UPDATED e POST_DELETED.
3.1Objeto Post
idstring- Identificador único do post. Salve no seu banco de dados: é por ele que as atualizações e a exclusão chegam. Trate como texto, sem presumir formato.
slugstring- Versão amigável do título, usada para montar a URL do post.
statusenum- Situação do post:
draftquando é rascunho,futurequando está agendado epublishquando está publicado. titlestring- Título do post.
contentobject- O conteúdo do post em mais de um formato.
content.textstring- Conteúdo em texto puro, sem formatação, com uma quebra de linha entre os blocos.
content.htmlstring- Conteúdo formatado em HTML.
content.richnull- Campo legado (Rich Text). Hoje é sempre
null: use ocontent.html.
descriptionstring- Descrição breve do post (a meta description).
featured_imageobject- A imagem de destaque do post.
featured_image.urlstring | null- URL da imagem.
nullquando o post não tem imagem. featured_image.filenamestring | null- Nome do arquivo da imagem.
featured_image.alt_textstring- Texto alternativo da imagem, usado para acessibilidade.
categoryobject- A categoria do post. Quando o post não tem categoria, o objeto vem com os dois campos vazios (nunca
null).category.idstring- Identificador único da categoria.
category.namestring- Nome da categoria.
publication_datetimestamp | null- Data de publicação (ou do agendamento) em UNIX, em segundos.
nullenquanto o post não tem data.
{
"id": "1700496185550x505140687844954560",
"slug": "slug-do-post",
"status": "draft",
"title": "Post de teste",
"content": {
"text": "Primeira seção\nConteúdo",
"html": "<h2>Primeira seção</h2><p>Conteúdo</p>",
"rich": null
},
"description": "Este é um post de teste",
"featured_image": {
"url": "https://exemplo.com/imagens/posts-lista-de-posts.png",
"filename": "posts-lista-de-posts.png",
"alt_text": "Texto alternativo da imagem"
},
"category": {
"id": "1699504216353x207539644452128000",
"name": "Nome da categoria"
},
"publication_date": 1699880198
}{
"category": {
"id": "",
"name": ""
}
}3.2Evento POST_CREATED
Enviado quando um post é criado na plataforma, ainda como rascunho. Rascunho totalmente vazio (sem título e sem texto) não é enviado.
{
"event": "POST_CREATED",
"post": {
"id": "1700496185550x505140687844954560",
"slug": "slug-do-post",
"status": "draft",
"title": "Post de teste",
"content": {
"text": "Primeira seção\nConteúdo",
"html": "<h2>Primeira seção</h2><p>Conteúdo</p>",
"rich": null
},
"description": "Este é um post de teste",
"featured_image": {
"url": "https://exemplo.com/imagens/posts-lista-de-posts.png",
"filename": "posts-lista-de-posts.png",
"alt_text": "Texto alternativo da imagem"
},
"category": {
"id": "1699504216353x207539644452128000",
"name": "Nome da categoria"
},
"publication_date": 1699880198
}
}3.3Evento POST_UPDATED
Enviado quando um post é alterado. Vale para o conteúdo e também para status, agendamento, imagem, categoria e as demais informações. É por este evento que você fica sabendo que um post foi publicado (status passa a publish) ou voltou para rascunho.
Trate o POST_UPDATED como “criar ou atualizar”: se o post.id ainda não existir do seu lado, crie o post.
{
"event": "POST_UPDATED",
"post": {
"id": "1700496185550x505140687844954560",
"slug": "slug-do-post",
"status": "publish",
"title": "Post de teste",
"content": {
"text": "Primeira seção\nConteúdo",
"html": "<h2>Primeira seção</h2><p>Conteúdo</p>",
"rich": null
},
"description": "Este é um post de teste",
"featured_image": {
"url": "https://exemplo.com/imagens/posts-lista-de-posts.png",
"filename": "posts-lista-de-posts.png",
"alt_text": "Texto alternativo da imagem"
},
"category": {
"id": "1699504216353x207539644452128000",
"name": "Nome da categoria"
},
"publication_date": 1699880198
}
}3.4Evento POST_DELETED
Enviado quando um post é excluído da plataforma. Leva só o id.
{
"event": "POST_DELETED",
"post": {
"id": "1700496185550x505140687844954560"
}
}3.5Resposta com a URL do post
Opcional, e recomendado: ao responder um POST_CREATED ou POST_UPDATED, devolva a URL pública do post. A Automarticles guarda esse endereço e passa a usá-lo como o link do post.
{
"post": {
"url": "https://seusite.com/blog/slug-do-post"
}
}Categoria
A Automarticles envia três eventos de categoria: CATEGORY_CREATED, CATEGORY_UPDATED e CATEGORY_DELETED.
4.1Objeto Category
idstring- Identificador único da categoria. Salve no seu banco de dados: é por ele que as atualizações e a exclusão chegam.
namestring- Nome da categoria no blog.
{
"id": "1699504216353x207539644452128000",
"name": "Nome da categoria"
}4.2Evento CATEGORY_CREATED
Enviado quando uma categoria é criada na plataforma.
{
"event": "CATEGORY_CREATED",
"category": {
"id": "1699504216353x207539644452128000",
"name": "Nome da categoria"
}
}4.3Evento CATEGORY_UPDATED
Enviado quando uma categoria é alterada na plataforma.
{
"event": "CATEGORY_UPDATED",
"category": {
"id": "1699504216353x207539644452128000",
"name": "Nome da categoria"
}
}4.4Evento CATEGORY_DELETED
Enviado quando uma categoria é apagada na plataforma. O objeto replace_to é opcional: quando vem, traz a categoria que passa a receber os posts da categoria apagada. Sem ele, esses posts ficam sem categoria.
{
"event": "CATEGORY_DELETED",
"category": {
"id": "1699504216353x207539644452128000",
"name": "Categoria excluída"
},
"replace_to": {
"id": "1700480211667x178676794280218533",
"name": "Nova categoria"
}
}Entrega e logs
- Cada evento é um
POSTcomContent-Type: application/jsone o cabeçalhoaccess-token. - Responda com um status
2xxem até 15 segundos. Qualquer outro status, ou a falta de resposta nesse prazo, conta como falha. - Não há reenvio automático. Toda entrega, com sucesso ou com falha, fica registrada em Configurações › Integrações › Webhook › Logs de envio, com o corpo enviado e a resposta recebida, e pode ser reenviada por lá no botão Reenviar.
- A URL precisa ser pública, em
httpouhttps, e sem usuário e senha no endereço. Endereços de rede interna são recusados. Redirecionamentos são seguidos (até três). - Como um mesmo post pode gerar vários eventos, faça o seu endpoint gravar por
id(criar se não existe, atualizar se existe), para que receber o mesmo evento duas vezes não duplique nada.