Black Friday50% off and double credits on the annual planSee the offer

Documentation · Automarticles

Webhooks Documentation

Learn how to receive Automarticles posts and categories in your own system.

On this page

Introduction

This documentation describes how to use Automarticles webhooks to automate your blog. On every post or category event, Automarticles sends a POST request with a JSON body to the URL you configure, and your system decides what to do with it: create the post, update it, unpublish it, delete it.

The event name always comes in the event field of the body. There are seven: CHECK_INTEGRATION, POST_CREATED, POST_UPDATED, POST_DELETED, CATEGORY_CREATED, CATEGORY_UPDATED and CATEGORY_DELETED.

Authentication

Every webhook request carries an access token in the access-token header. You will find this token in Automarticles, under Settings › Integrations › Webhook, in the Authentication Token field.

In your endpoint, compare the header value with your token before processing anything, and reject (401) any request that comes without it or with a different value.

Before turning delivery on and receiving events, you need to verify the integration with the procedure below.

2.1Event CHECK_INTEGRATION

CHECK_INTEGRATION is the initial test: it confirms that Automarticles can reach your system and that the token is being recognized. Step by step:

  1. Under Settings › Integrations › Webhook, fill in the Webhook URL field with the address that will receive the events, and save.
  2. Click Verify. We send a POST to your URL with the token in the access-token header and the body below.
  3. Your endpoint must answer with a 2xx status and a JSON that returns exactly the same token it received.
  4. Once the returned token matches the one we sent, the integration is verified and you can turn on Send webhooks.
Body we send
{
  "event": "CHECK_INTEGRATION"
}
Expected response
{
  "token": "SEU_TOKEN_AQUI"
}
Events are only sent while the integration is verified and delivery is turned on. Generating a new token turns both off: update the token in your system and verify again.

Post

Automarticles sends three post events: POST_CREATED, POST_UPDATED and POST_DELETED.

3.1Object Post

idstring
Unique identifier of the post. Store it in your database: updates and deletion arrive by it. Treat it as text, without assuming a format.
slugstring
URL-friendly version of the title, used to build the post URL.
statusenum
State of the post: draft when it is a draft, future when it is scheduled and publish when it is published.
titlestring
Post title.
contentobject
The post content in more than one format.
content.textstring
Content as plain text, with no formatting and a line break between blocks.
content.htmlstring
Content formatted as HTML.
content.richnull
Legacy field (Rich Text). It is always null today: use content.html.
descriptionstring
Short description of the post (the meta description).
featured_imageobject
The featured image of the post.
featured_image.urlstring | null
Image URL. null when the post has no image.
featured_image.filenamestring | null
Image file name.
featured_image.alt_textstring
Alternative text for the image, used for accessibility.
categoryobject
The post category. When the post has no category, the object comes with both fields empty (never null).
category.idstring
Unique identifier of the category.
category.namestring
Category name.
publication_datetimestamp | null
Publication (or scheduling) date as a UNIX timestamp, in seconds. null while the post has no date.
Example
{
  "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 without a category
{
  "category": {
    "id": "",
    "name": ""
  }
}

3.2Event POST_CREATED

Sent when a post is created on the platform, still as a draft. A completely empty draft (no title and no text) is not sent.

{
  "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.3Event POST_UPDATED

Sent when a post changes. That covers the content and also status, scheduling, image, category and the other fields. This is the event that tells you a post was published (status becomes publish) or went back to draft.

Treat POST_UPDATED as “create or update”: if the post.id does not exist on your side yet, create the 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.4Event POST_DELETED

Sent when a post is deleted from the platform. It carries only the id.

{
  "event": "POST_DELETED",
  "post": {
    "id": "1700496185550x505140687844954560"
  }
}

3.5Response with the post URL

Optional, and recommended: when answering a POST_CREATED or POST_UPDATED, return the public URL of the post. Automarticles stores that address and uses it as the link to the post.

Recommended response
{
  "post": {
    "url": "https://seusite.com/blog/slug-do-post"
  }
}

Category

Automarticles sends three category events: CATEGORY_CREATED, CATEGORY_UPDATED and CATEGORY_DELETED.

4.1Object Category

idstring
Unique identifier of the category. Store it in your database: updates and deletion arrive by it.
namestring
Category name in the blog.
Example
{
  "id": "1699504216353x207539644452128000",
  "name": "Nome da categoria"
}

4.2Event CATEGORY_CREATED

Sent when a category is created on the platform.

{
  "event": "CATEGORY_CREATED",
  "category": {
    "id": "1699504216353x207539644452128000",
    "name": "Nome da categoria"
  }
}

4.3Event CATEGORY_UPDATED

Sent when a category is changed on the platform.

{
  "event": "CATEGORY_UPDATED",
  "category": {
    "id": "1699504216353x207539644452128000",
    "name": "Nome da categoria"
  }
}

4.4Event CATEGORY_DELETED

Sent when a category is deleted on the platform. The replace_to object is optional: when present, it carries the category that takes over the posts of the deleted one. Without it, those posts are left without a category.

{
  "event": "CATEGORY_DELETED",
  "category": {
    "id": "1699504216353x207539644452128000",
    "name": "Categoria excluída"
  },
  "replace_to": {
    "id": "1700480211667x178676794280218533",
    "name": "Nova categoria"
  }
}

Delivery and logs

  • Each event is a POST with Content-Type: application/json and the access-token header.
  • Answer with a 2xx status within 15 seconds. Any other status, or no answer in that time, counts as a failure.
  • There is no automatic retry. Every delivery, successful or not, is recorded under Settings › Integrations › Webhook › Delivery logs, with the body we sent and the response we got, and can be sent again from there with the Resend button.
  • The URL must be public, on http or https, with no username and password in the address. Internal network addresses are refused. Redirects are followed (up to three).
  • Since one post can produce several events, make your endpoint write by id (create if missing, update if present), so receiving the same event twice does not duplicate anything.

Any questions?

Reach us by email at

contato@automarticles.com