Black Friday50% off e créditos em dobro no anualVer oferta

Documentação · Automarticles

Documentação de Webhooks

Aprenda a receber os posts e as categorias da Automarticles no seu próprio sistema.

Nesta página

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:

  1. Em Configurações › Integrações › Webhook, preencha o campo URL do Webhook com o endereço que vai receber os eventos e salve.
  2. Clique em Verificar. Enviamos um POST para a sua URL com o token no cabeçalho access-token e o corpo abaixo.
  3. O seu endpoint precisa responder com status 2xx e um JSON que devolve exatamente o mesmo token recebido.
  4. Com o token devolvido igual ao enviado, a integração fica verificada e você pode ligar a opção Enviar webhooks.
Corpo que enviamos
{
  "event": "CHECK_INTEGRATION"
}
Resposta esperada
{
  "token": "SEU_TOKEN_AQUI"
}
Os eventos só são enviados com a integração verificada e o envio ativado. Ao gerar um novo token, a verificação e o envio são desligados: atualize o token no seu sistema e verifique de novo.

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: draft quando é rascunho, future quando está agendado e publish quando 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 o content.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. null quando 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. null enquanto o post não tem data.
Exemplo
{
  "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
}
Post sem categoria
{
  "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.

Resposta recomendada
{
  "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.
Exemplo
{
  "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 POST com Content-Type: application/json e o cabeçalho access-token.
  • Responda com um status 2xx em 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 http ou https, 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.

Ficou com alguma dúvida?

Fale com a gente pelo e-mail

contato@automarticles.com