🔗 API e webhooks

Por padrão, a API pública do Postiz vem desligada. Para evitar que alguém abuse do seu endpoint, é preciso ativar via flag no .env e reiniciar o stack. Depois disso, todos os endpoints ficam disponíveis em /api na mesma porta do app.

O endpoint base segue o padrão {MAIN_URL}/api. Em dev local, vira http://localhost:5000/api. Em produção atrás de domínio, https://postiz.seudominio.com/api.

# ~/postiz/.env — adicione (ou descomente)
API_LIMIT=30
NX_ADD_PLUGINS=false

# Habilitar API pública
IS_GENERAL=true
DISABLE_REGISTRATION=false

# (Opcional) restringir CORS a um domínio específico
FRONTEND_URL=http://localhost:5000

# Aplicar e reiniciar
docker compose up -d --force-recreate postiz

# Smoke test do endpoint base
curl -i http://localhost:5000/api/health
# HTTP/1.1 200 OK
# {"status":"ok"}

Conceitos-chave

A API do Postiz autentica via Bearer token no header Authorization. Cada chave fica vinculada a um usuário e herda os scopes dele — ou seja, só consegue publicar nas contas de redes sociais que aquele usuário conectou.

Na UI: Settings → API Keys → Create new key. Copie o valor na hora — depois que a modal fecha, o token nunca mais aparece (só o hash fica no banco).

# Exemplo de chave gerada (formato real)
pk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

# Guarde em variável de ambiente, nunca no código
export POSTIZ_API_KEY="pk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
export POSTIZ_API_URL="http://localhost:5000/api"

# Testar a chave (lista contas conectadas)
curl -s -H "Authorization: Bearer $POSTIZ_API_KEY" \
  $POSTIZ_API_URL/integrations \
  | jq '.[].name'

Conceitos-chave

O endpoint POST /api/posts é o coração da API. Você manda um JSON descrevendo o conteúdo, em quais integrações publicar e quando. O Postiz responde com o postId e enfileira o trabalho no BullMQ.

Os três campos obrigatórios são type (draft, schedule ou now), date (ISO 8601 em UTC) e posts — array com um item por integração.

# Body JSON: agendar um post no LinkedIn e no X
cat > payload.json <<'EOF'
{
  "type": "schedule",
  "date": "2026-06-01T14:30:00.000Z",
  "shortLink": false,
  "tags": ["lançamento", "produto"],
  "posts": [
    {
      "integration": { "id": "ckxlinkedin123" },
      "value": [
        {
          "content": "Lançamos uma feature nova: agendamento em massa via API. Quem usa Postiz, vai amar.",
          "image": []
        }
      ],
      "group": null,
      "settings": {}
    },
    {
      "integration": { "id": "ckxtwitter456" },
      "value": [
        { "content": "Postiz agora aceita agendamento via API REST. 🚀", "image": [] },
        { "content": "Detalhes no thread abaixo 👇", "image": [] }
      ],
      "group": null,
      "settings": {}
    }
  ]
}
EOF

# Disparar o POST
curl -X POST "$POSTIZ_API_URL/posts" \
  -H "Authorization: Bearer $POSTIZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json

# Resposta esperada (201 Created)
# {
#   "postId": "ckxpost789abc",
#   "scheduledFor": "2026-06-01T14:30:00.000Z",
#   "status": "QUEUED",
#   "integrations": ["ckxlinkedin123", "ckxtwitter456"]
# }

Conceitos-chave

Como o POST inicial só enfileira o trabalho, o jeito limpo de saber o resultado é receber um webhook. O Postiz dispara um POST para a URL que você cadastrar sempre que um post muda de estado — PUBLISHED, FAILED ou DELETED.

Cadastre o callback em Settings → Webhooks → Add URL. Cada webhook tem um secret usado para assinar o payload no header X-Postiz-Signature — valide isso no seu lado pra confirmar que a requisição veio mesmo do Postiz.

# Payload que o Postiz envia para sua URL
{
  "event": "post.published",
  "timestamp": "2026-06-01T14:30:12.482Z",
  "data": {
    "postId": "ckxpost789abc",
    "status": "PUBLISHED",
    "integration": {
      "id": "ckxlinkedin123",
      "provider": "linkedin",
      "name": "Minha Página LinkedIn"
    },
    "publishedAt": "2026-06-01T14:30:12.000Z",
    "remoteId": "urn:li:share:7203451829",
    "remoteUrl": "https://www.linkedin.com/feed/update/urn:li:share:7203451829/",
    "tags": ["lançamento", "produto"]
  }
}

# Payload de falha (mesma estrutura, status diferente)
{
  "event": "post.failed",
  "timestamp": "2026-06-01T14:30:09.117Z",
  "data": {
    "postId": "ckxpost789abc",
    "status": "FAILED",
    "integration": { "id": "ckxtwitter456", "provider": "x" },
    "error": {
      "code": "RATE_LIMITED",
      "message": "X API: 429 too many requests; retry after 900s"
    },
    "willRetry": true,
    "retryAt": "2026-06-01T14:45:09.000Z"
  }
}

Conceitos-chave

Tanto n8n quanto Make.com têm nodes nativos do Postiz (community node no n8n; módulo oficial no Make). Eles encapsulam a autenticação Bearer e expõem ações como Create Post, List Integrations, Delete Post. Se preferir, use o HTTP Request node genérico — funciona igual.

Para receber webhooks no n8n, use o Webhook node como trigger e cole a URL gerada no painel de webhooks do Postiz. No Make, use o módulo Custom Webhook.

# Exemplo: n8n HTTP Request node configurado manualmente
{
  "method": "POST",
  "url": "={{ $env.POSTIZ_API_URL }}/posts",
  "authentication": "genericCredentialType",
  "genericAuthType": "httpHeaderAuth",
  "sendHeaders": true,
  "headerParameters": {
    "parameters": [
      { "name": "Authorization", "value": "Bearer {{ $env.POSTIZ_API_KEY }}" },
      { "name": "Content-Type", "value": "application/json" }
    ]
  },
  "sendBody": true,
  "bodyContentType": "json",
  "jsonBody": "={{ JSON.stringify($json.payload) }}"
}

Conceitos-chave

O grande motivo de usar a API do Postiz em vez de integrar direto com cada rede é não reinventar OAuth, renovação de tokens, rate limit e idempotência N vezes. Seu app fala com uma API consistente; o Postiz cuida do resto.

# Arquitetura recomendada
[ Seu App ]
     |
     | (1) POST /api/posts  — Bearer token
     v
[ Postiz API ]
     |
     | (2) enfileira no Redis (BullMQ)
     v
[ Worker Postiz ]
     |
     | (3) chama API de cada rede (OAuth gerenciado pelo Postiz)
     v
[ LinkedIn ] [ X ] [ Instagram ] [ Bluesky ] ...
     |
     | (4) sucesso/erro
     v
[ Postiz ]
     |
     | (5) POST webhook  → https://seuapp.com/webhooks/postiz
     v
[ Seu App ]  (atualiza DB, dispara notificação ao usuário)

Conceitos-chave