Verificação de webhook

Os callbacks são disparados pelos servidores do Scanify para o callbackUrl que você informou. Garantir que a requisição realmente veio do Scanify é responsabilidade da sua aplicação.

Mecanismos disponíveis

As duas opções podem ser combinadas.

`callbackAuthToken` (recomendado)

Se você informar callbackAuthToken na requisição original, o Scanify envia esse valor no header Authorization do callback:

Authorization: Bearer <callbackAuthToken>

Defina um valor secreto e único por endpoint, guarde-o em uma variável de ambiente do seu servidor e compare no recebimento.

import express from 'express';

const app = express();
app.use(express.json());

app.post('/webhooks/scanify', (req, res) => {
  const auth = req.header('authorization');
  const expected = `Bearer ${process.env.SCANIFY_WEBHOOK_TOKEN}`;

  if (auth !== expected) {
    return res.status(401).end();
  }

  res.status(200).end();
});

`signature`

Se você informar signature na requisição original, o Scanify reenvia a mesma string, sem modificação, no header:

x-scanify-signature: <signature>

É útil para correlacionar o callback com a requisição que o originou (ex: codifique aí um id interno).

Este NÃO é um HMAC calculado pelo Scanify. É apenas um eco do valor que você enviou. Não use como assinatura criptográfica.

Idempotência

O Scanify reenvia o callback em caso de falha: até 3 tentativas com backoff exponencial. Sua aplicação deve tratar entregas duplicadas como normais. Use request_id como chave única de deduplicação:

if (await db.webhookEvents.exists(payload.request_id)) {
  return res.status(200).end();
}

await db.webhookEvents.create({ request_id: payload.request_id });
// ... processar

Boas práticas

Responda 2xx rapidamente. Processamento pesado deve ir para uma fila no seu lado.
Restrinja o endpoint por IP ou região se a sua infraestrutura permitir.
Nunca logue o callbackAuthToken em texto claro.
Habilite HTTPS no endpoint. HTTP simples é aceito mas não é recomendado.

Para o formato do corpo enviado no callback, veja Callback URL e Payload de resposta.

​Mecanismos disponíveis

​callbackAuthToken (recomendado)

​signature

​Idempotência

​Boas práticas

Mecanismos disponíveis

`callbackAuthToken` (recomendado)

`signature`

Idempotência

Boas práticas