Webhooks do Flux

Em vez de perguntar à API de tempo em tempo se algo mudou, cadastre um endereço e o Flux avisa no instante em que muda: um post criado, agendado, publicado ou com falha, uma decisão de aprovação, uma conta conectada que caiu ou voltou.

O modelo é o dos webhooks do Stripe: você escolhe os eventos e os projetos, cada aviso chega num envelope padronizado e assinado, e o que falha é reenviado com espaçamento crescente.

Cadastrar um webhook

O cadastro é feito na tela da conta, e não pela API. Já autenticado no Flux, acesse Empresa → Webhooks, em /company/edit/webhooks

1. 1Clique em Criar webhook.
2. 2Informe o endereço (URL https) que vai receber os avisos e, se quiser, uma descrição.
3. 3Marque os eventos que esse endereço deve receber (ao menos um).
4. 4Escolha os projetos: todos os atuais e os próximos, ou uma seleção.
5. 5Salve e copie o segredo (whsec_…). É com ele que você confere a assinatura de cada aviso.

Depois de cadastrado

Eventos

Os eventos estão agrupados como na tela de cadastro. O objeto é o que vem em data.object: o post ou a conta conectada.

Particularidades

O envelope

Todo aviso é um POST com corpo JSON neste formato, igual para os 9 eventos:

{
  "id": "evt_01j9x7qk2p8vyq4h5t3m6n0rzb",
  "object": "event",
  "type": "post.published",
  "api_version": "v1",
  "created": 1790236812,
  "livemode": true,
  "data": {
    "object": { "id": 184931, "status": "published", "...": "..." },
    "previous_attributes": { "status": "publishing", "published_url": null }
  }
}

Cabeçalhos

Exemplos por evento

O post vem igual ao GET /api/v1/posts/{id}, bloco review incluído; a conta conectada, igual ao GET /api/v1/integrations.

{
  "id": "evt_01j9x7qk2p8vyq4h5t3m6n0rzb",
  "object": "event",
  "type": "post.published",
  "api_version": "v1",
  "created": 1790326812,
  "livemode": true,
  "data": {
    "object": {
      "id": 184931,
      "asset_group_id": 71204,
      "project": { "id": 3312, "name": "Padaria Aurora", "timezone": "America/Sao_Paulo" },
      "network": "instagram",
      "network_group": "instagram",
      "account": { "id": "17841404295825681", "name": "padariaaurora" },
      "type": "feed",
      "status": "published",
      "review_status": null,
      "caption": "O pão na pedra sai às 7h.",
      "first_comment": "#padaria",
      "schedule_at": "2026-09-25T07:00:00-03:00",
      "published_url": "https://www.instagram.com/p/DAbC123xYz/",
      "media": [
        {
          "id": 998812,
          "type": "image",
          "url": "https://midias.reportei.com/flux-upload/...",
          "url_expires_at": "2026-09-27T07:00:12-03:00",
          "width": 1080,
          "height": 1350,
          "aspect_ratio": "4:5"
        }
      ],
      "created_at": "2026-09-21T09:22:10-03:00",
      "updated_at": "2026-09-25T07:00:12-03:00",
      "review": null
    },
    "previous_attributes": {
      "status": "publishing",
      "published_url": null
    }
  }
}

Verificar a assinatura

Cada aviso leva o cabeçalho Flux-Signature, no mesmo formato do Stripe-Signature. Qualquer biblioteca de verificação do Stripe se adapta trocando o nome do cabeçalho:

Flux-Signature: t=1790236812,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd

v1 é o HMAC-SHA256, em hexadecimal, de "{t}.{corpo}" com o segredo do webhook (whsec_…). Para conferir:

1. 1Leia o corpo bruto, antes de qualquer parse de JSON. Reserializar muda os bytes e a assinatura deixa de bater.
2. 2Calcule o HMAC e compare com cada v1 do cabeçalho em tempo constante. Durante a troca de segredo chegam dois v1, o novo e o antigo, por 24 horas: aceite se qualquer um bater.
3. 3Recuse se t estiver a mais de 5 minutos do seu relógio: isso protege contra o reenvio malicioso de um aviso antigo.

function fluxSignatureIsValid(string $body, string $header, string $secret): bool
{
    parse_str(str_replace(',', '&', $header), $parts);
    preg_match_all('/v1=([a-f0-9]{64})/', $header, $signatures);

    $timestamp = (int) ($parts['t'] ?? 0);
    if (abs(time() - $timestamp) > 300) {
        return false;
    }

    $expected = hash_hmac('sha256', $timestamp . '.' . $body, $secret);

    foreach ($signatures[1] as $signature) {
        if (hash_equals($expected, $signature)) {
            return true;
        }
    }

    return false;
}

$valid = fluxSignatureIsValid(file_get_contents('php://input'), $_SERVER['HTTP_FLUX_SIGNATURE'] ?? '', $secret);

Entrega e tentativas

O Flux considera entregue só a resposta 2xx. Qualquer outra coisa conta como falha e entra no ciclo de tentativas.

Tentativas

Uma entrega que falha é reenviada até 8 vezes, em cerca de 3 dias:

Endereço que só falha

Boas práticas

Códigos de falha

O data.object.failure.code de um post.failed é um destes códigos. A lista é estável: tratamento condicional por código é seguro.