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:
- Under Settings › Integrations › Webhook, fill in the Webhook URL field with the address that will receive the events, and save.
- Click Verify. We send a
POSTto your URL with the token in theaccess-tokenheader and the body below. - Your endpoint must answer with a
2xxstatus and a JSON that returns exactly the same token it received. - Once the returned token matches the one we sent, the integration is verified and you can turn on Send webhooks.
{
"event": "CHECK_INTEGRATION"
}{
"token": "SEU_TOKEN_AQUI"
}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:
draftwhen it is a draft,futurewhen it is scheduled andpublishwhen 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
nulltoday: usecontent.html.
descriptionstring- Short description of the post (the meta description).
featured_imageobject- The featured image of the post.
featured_image.urlstring | null- Image URL.
nullwhen 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.
nullwhile the post has no date.
{
"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.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.
{
"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.
{
"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
POSTwithContent-Type: application/jsonand theaccess-tokenheader. - Answer with a
2xxstatus 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
httporhttps, 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.