Como criar integrações próprias usando webhooks

A regra “Postar em Webhook” permite automatizar o envio de novas publicações de feeds RSS para o endpoint de webhook que você especificar, assim que elas estiverem disponíveis. Você também pode definir palavras-chave para filtrar quais publicações serão enviadas. Quando uma nova publicação corresponder aos seus critérios, ela será enviada ao endpoint como uma solicitação POST no formato JSON.

Formato do payload JSON

Cada solicitação POST enviada ao seu webhook contém dois elementos principais: post e feed.

Ela também contém elementos de metadados que identificam a mensagem do webhook. O campo version indica qual versão da API de webhooks do Feeder está sendo usada. O valor da versão é sempre 2023-06-26 e será atualizado se houver alterações incompatíveis.

{
  "version": "2023-06-26",
  "message_id": "a unique UUID for this message, will be constant during retries",
  "feed": { ... },
  "post": { ... }
}

O elemento post contém informações sobre a publicação:

{
  "id": "The unique identifier of the post",
  "title": "The title of the post",
  "url": "The URL where the post can be accessed",
  "published": "The date and time when the post was published",
  "content": "The content of the post",
  "audio_url": "link to mp3 attached to post (if present)",
  "image_url": "link to image attached to post (if present)
}

Observação: published será null se o feed RSS não especificar uma data de publicação válida.

O elemento feed fornece informações sobre o feed de origem da publicação:

{
  "id": "The unique identifier of the feed",
  "source_url": "The URL of the source, for example RSS/Atom feed URL",
  "public_url": "The source's self identified public URL",
  "title": "The title of the feed",
  "favicon": "The URL of the feed's favicon"
}

Podemos acrescentar campos a esses objetos no futuro. Se estiver faltando alguma informação, entre em contato conosco.

Lógica de novas tentativas

Se uma solicitação falhar, o Feeder tentará enviá-la novamente automaticamente. Se uma solicitação POST não receber um código de resposta HTTP entre 200 e 399, tentaremos reenviá-la de acordo com o cronograma abaixo, definido em segundos:

• Tentativa 1: após 5 segundos
• Tentativa 2: após 30 segundos
• Tentativa 3: após 60 segundos
• Tentativa 4: após 5 minutos
• Tentativa 5: após 10 minutos
• Tentativa 6: após 30 minutos
• Tentativa 7: após 30 minutos
• Tentativa 8: após 30 minutos

Observação: esse mecanismo de novas tentativas é acionado apenas por eventos reais de publicação e não se aplica às notificações de teste. Os intervalos também podem mudar.

Depuração

Se ocorrerem erros, você poderá encontrá-los no registro de execução da ação. Acesse a regra que não está funcionando e selecione “Open error log”.

Lá, você verá mais detalhes sobre os webhooks que falharam.

Configurar seu webhook

Para configurar seu webhook:

1. Acesse a página Regras.
2. Crie uma nova regra.
3. Informe o nome, os feeds e os critérios.
4. Na seção “O que deve acontecer?”, escolha “Postar em Webhook”.
5. Insira o URL do webhook no campo de texto indicado.
6. Para confirmar que tudo está configurado corretamente, use o botão “Enviar mensagem de teste” para enviar uma notificação de teste ao seu endpoint. Essa é apenas uma mensagem de teste e, se ela falhar, não acionará a lógica de novas tentativas. Além disso, para que a mensagem de teste seja enviada, sua conta precisa ter pelo menos 1 feed com publicações.

Segurança: verificar assinaturas de webhook

Para confirmar que as solicitações de webhook recebidas são realmente do Feeder e não foram adulteradas, você pode verificar o segredo de webhook gerado para cada webhook. Cada solicitação de webhook inclui um cabeçalho X-Feeder-Signature com uma assinatura HMAC-SHA256 do corpo da solicitação.

Como funciona

1. Nas configurações da regra, ative a opção “Avançado”. Você verá uma sequência de caracteres no campo “Webhook Secret”.
2. Quando o Feeder envia um webhook ao seu endpoint, calcula um hash HMAC-SHA256 do corpo da solicitação JSON, usando seu segredo como chave.
3. A assinatura resultante é enviada no cabeçalho X-Feeder-Signature, com o prefixo sha256=. Por exemplo:

   X-Feeder-Signature: sha256=a1b2c3d4e5f6...

4. No seu servidor, calcule o mesmo hash HMAC-SHA256 usando o corpo bruto da solicitação e sua cópia do segredo. Em seguida, compare-o com o valor do cabeçalho.

Por que usar isso?

• Autenticidade: confirma que a solicitação foi enviada pelo Feeder, e não por terceiros.
• Integridade: garante que o payload não foi alterado durante o envio.

Verificar a assinatura

Para verificar:

1. Leia o corpo bruto da solicitação como uma string, sem analisá-lo primeiro.
2. Calcule o HMAC-SHA256 dessa string usando seu segredo.
3. Compare a assinatura calculada com o valor do cabeçalho X-Feeder-Signature usando uma comparação segura contra ataques de temporização.

Exemplo: Node.js (Express)

const crypto = require("crypto");

const WEBHOOK_SECRET = process.env.FEEDER_WEBHOOK_SECRET;

function verifyFeederSignature(req, res, next) {
  const signature = req.headers["x-feeder-signature"];
  if (!signature) {
    return res.status(401).send("Missing signature");
  }

  const expectedSignature =
    "sha256=" +
    crypto.createHmac("sha256", WEBHOOK_SECRET).update(req.body).digest("hex");

  const isValid = crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );

  if (!isValid) {
    return res.status(401).send("Invalid signature");
  }

  next();
}

// Important: use express.raw() so req.body is the raw string, not parsed JSON
app.post(
  "/webhook",
  express.raw({ type: "application/json" }),
  verifyFeederSignature,
  (req, res) => {
    const payload = JSON.parse(req.body);
    // Handle the webhook payload
    console.log("Received verified webhook:", payload);
    res.sendStatus(200);
  }
);

Importante: para verificar a assinatura, você precisa acessar o corpo bruto da solicitação. Se a sua estrutura de aplicação analisar o corpo JSON antes de calcular o HMAC, a string serializada novamente poderá ser diferente da original e a assinatura não corresponderá. No Express, use express.raw({ type: "application/json" }) na rota do webhook, como mostrado acima.

Mais alguma dúvida?

Fale com a gente pelo e-mail support@feeder.co.