Webhooks

Um webhook é um endereço no seu servidor que o Posty5 chama quando algo acontece. Em vez de consultar o Posty5 sobre novas visitas, seu sistema é avisado em segundos, com um evento JSON que pode verificar.

Nota

Os webhooks dependem do seu plano. As entregas não custam créditos. Veja a página de créditos para mais detalhes. Créditos de recursos

Criar um endpoint

1. No painel do Posty5, abra Configurações da conta e escolha Webhooks.

2. Adicione um endpoint, informe o endereço HTTPS e escolha os eventos que ele recebe.

3. Escolha todos os seus links e códigos QR ou só alguns, se visitas de bots contam e se os eventos chegam um a um ou em lotes.

4. Salve e copie o segredo de assinatura. Ele é exibido só desta vez.

5. Use Enviar teste para verificar se o seu servidor recebe e valida um evento webhook.test.

O endereço deve usar HTTPS e ser acessível pela internet. Endereços de redes privadas e locais são recusados, e redirecionamentos não são seguidos. Você pode ter até 10 endpoints.

Eventos

Event
short_link.visited	Alguém abriu um dos seus links curtos, inclusive pela imagem QR do link.
short_link.visits_milestone	Um link curto atingiu uma das contagens de visitas que você definiu (até 10 valores).
qr_code.scanned	Alguém escaneou um dos seus códigos QR dinâmicos.
qr_code.scans_milestone	Um código QR atingiu uma das contagens de leituras que você definiu.
webhook.test	Enviado apenas quando você usa Enviar teste.

Os eventos de visita e de leitura ainda não são enviados

Hoje o Posty5 envia apenas o evento de teste. Os eventos de visita e de leitura, e seus marcos, começam quando as análises de visitas forem lançadas. Você já pode criar e testar endpoints, e eles passarão a receber esses eventos sem nenhuma alteração.

Códigos QR estáticos não enviam eventos

Um código QR estático guarda o conteúdo diretamente, então uma leitura nunca chega ao Posty5 e nenhum evento pode ser enviado. Apenas códigos QR dinâmicos e links curtos geram eventos.

Como é um evento

Cada evento é um POST JSON com um id, um tipo, a versão da API, o horário de criação e seus dados, o link ou código QR e a visita.

{
  "id": "evt_6700f1c2a9e4b51d2c3f0a11",
  "type": "short_link.visited",
  "apiVersion": "2026-10-01",
  "createdAt": "2026-10-04T12:00:00.000Z",
  "data": {
    "target": {
      "type": "shortLink",
      "id": "66f0c2a9e4b51d2c3f0a1122",
      "code": "aB3xY9",
      "url": "https://pst5.com/_aB3xY9",
      "name": "Spring sale",
      "destinationUrl": "https://shop.example/sale",
      "tag": "spring",
      "refId": null
    },
    "visit": {
      "at": "2026-10-04T11:59:59.120Z",
      "channel": "qr",
      "country": "EG",
      "deviceType": "mobile",
      "os": "Android",
      "browser": "Chrome",
      "referrerHost": null,
      "language": "ar",
      "isBot": false,
      "outcome": "redirect"
    }
  }
}

Eventos de marco trazem data.milestone com a métrica, o valor atingido e quando, sem visita.

Com a entrega em lotes, um POST do tipo batch traz até 500 eventos em data.events.

O que nunca é enviado

Os eventos nunca contêm o endereço IP do visitante, o user agent completo, o endereço de referência completo, um identificador do visitante ou o ID da sua conta. Visitas de bots ficam de fora, a menos que você as inclua.

Verifique a assinatura

O Posty5 assina cada entrega com o segredo do seu endpoint, seguindo a especificação Standard Webhooks, em três cabeçalhos. Rejeite qualquer requisição cuja assinatura não confira ou cujo timestamp tenha mais de 5 minutos.

• webhook-id
• webhook-timestamp
• webhook-signature

No Node.js, use o pacote @posty5/webhooks.

import { verifyWebhookSignature } from "@posty5/webhooks";

// rawBody is the request body exactly as received, before JSON parsing.
const event = verifyWebhookSignature({
  payload: rawBody,
  headers: request.headers,
  secret: process.env.POSTY5_WEBHOOK_SECRET,
});

No .NET, use o pacote Posty5.Webhooks.

using Posty5.Webhooks;

var webhookEvent = WebhookSignature.Verify(rawBody, headers, secret);

Em qualquer outra linguagem, qualquer biblioteca Standard Webhooks valida os eventos do Posty5 com o seu segredo.

Cuidado

Valide o corpo exatamente como foi recebido. Fazer o parse do JSON e serializá-lo de novo altera os bytes e quebra a assinatura.

Novas tentativas e falhas

• Responda com qualquer status 2xx em até 10 segundos. Qualquer outra coisa conta como falha.
• Uma entrega com falha é tentada de novo após 30 segundos, 2 minutos, 10 minutos, 1 hora, 6 horas e 24 horas, e depois é abandonada.
• Cada nova tentativa traz o mesmo webhook-id, para que o seu servidor possa ignorar um evento já processado.
• Um endpoint é desativado após 20 entregas com falha seguidas ao longo de pelo menos 24 horas, ou imediatamente se responder 410 Gone. Você recebe uma notificação e pode reativá-lo no painel.
• A lista de entregas do endpoint mostra cada tentativa com o status e a resposta do seu servidor, e permite reenviar uma entrega.

Trocar o segredo

Se o segredo pode ter vazado, troque-o pelo menu do endpoint. Por 24 horas as entregas trazem duas assinaturas, uma por segredo, para você atualizar o servidor sem perder eventos.

Sem código, no n8n

O nó Posty5 Trigger cria e valida o endpoint para você. n8n Posty5 Trigger