Webhooks

Un webhook es una dirección de tu servidor a la que Posty5 llama cuando ocurre algo. En lugar de preguntar a Posty5 por nuevas visitas, tu sistema recibe el aviso en segundos, con un evento JSON que puede verificar.

Nota

Los webhooks dependen de tu plan. Las entregas no cuestan créditos. Consulta la página de créditos para más detalles. Créditos de funciones

Crear un endpoint

1. En el panel de Posty5, abre Configuración de la cuenta y elige Webhooks.

2. Agrega un endpoint, ingresa su dirección HTTPS y elige los eventos que recibe.

3. Elige todos tus enlaces y códigos QR o solo algunos, si cuentan las visitas de bots y si los eventos llegan uno a uno o en lotes.

4. Guarda y copia el secreto de firma. Solo se muestra esta vez.

5. Usa Enviar prueba para comprobar que tu servidor recibe y verifica un evento webhook.test.

La dirección debe usar HTTPS y ser accesible desde internet. Se rechazan las direcciones de redes privadas y locales, y no se siguen redirecciones. Puedes tener hasta 10 endpoints.

Eventos

Event
short_link.visited	Alguien abrió uno de tus enlaces cortos, también a través de la imagen QR del enlace.
short_link.visits_milestone	Un enlace corto alcanzó uno de los recuentos de visitas que definiste (hasta 10 valores).
qr_code.scanned	Alguien escaneó uno de tus códigos QR dinámicos.
qr_code.scans_milestone	Un código QR alcanzó uno de los recuentos de escaneos que definiste.
webhook.test	Se envía solo cuando usas Enviar prueba.

Los eventos de visita y escaneo aún no se envían

Hoy Posty5 solo envía el evento de prueba. Los eventos de visita y escaneo, y sus hitos, empezarán cuando se publique la analítica de visitas. Ya puedes crear y probar endpoints, y empezarán a recibir esos eventos entonces sin ningún cambio.

Los códigos QR estáticos no envían eventos

Un código QR estático contiene su contenido directamente, así que un escaneo nunca llega a Posty5 y no se puede enviar ningún evento. Solo los códigos QR dinámicos y los enlaces cortos generan eventos.

Cómo es un evento

Cada evento es un POST JSON con un id, un tipo, la versión de la API, su hora de creación y sus datos, el enlace o código QR y la 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"
    }
  }
}

Los eventos de hito llevan data.milestone con la métrica, el valor alcanzado y cuándo, sin visita.

Con la entrega por lotes, un POST de tipo batch lleva hasta 500 eventos en data.events.

Lo que nunca se envía

Los eventos nunca contienen la dirección IP del visitante, el user agent completo, la dirección de referencia completa, un identificador del visitante ni el ID de tu cuenta. Las visitas de bots se excluyen salvo que las incluyas.

Verifica la firma

Posty5 firma cada entrega con el secreto de tu endpoint, según la especificación Standard Webhooks, en tres cabeceras. Rechaza cualquier solicitud cuya firma no coincida o cuya marca de tiempo tenga más de 5 minutos.

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

En Node.js, usa el paquete @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,
});

En .NET, usa el paquete Posty5.Webhooks.

using Posty5.Webhooks;

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

En cualquier otro lenguaje, cualquier biblioteca de Standard Webhooks verifica los eventos de Posty5 con tu secreto.

Precaución

Verifica el cuerpo exactamente como se recibió. Analizar el JSON y volver a serializarlo cambia los bytes y rompe la firma.

Reintentos y fallos

• Responde con cualquier estado 2xx en 10 segundos. Cualquier otra cosa cuenta como fallo.
• Una entrega fallida se reintenta tras 30 segundos, 2 minutos, 10 minutos, 1 hora, 6 horas y 24 horas, y luego se abandona.
• Cada reintento lleva el mismo webhook-id, para que tu servidor pueda ignorar un evento que ya procesó.
• Un endpoint se desactiva tras 20 entregas fallidas seguidas durante al menos 24 horas, o de inmediato si responde 410 Gone. Recibes una notificación y puedes reactivarlo desde el panel.
• La lista de entregas del endpoint muestra cada intento con su estado y la respuesta de tu servidor, y te permite reenviar una entrega.

Rotar el secreto

Si el secreto pudo filtrarse, rótalo desde el menú del endpoint. Durante 24 horas las entregas llevan dos firmas, una por secreto, para que actualices tu servidor sin perder eventos.

Sin código, en n8n

El nodo Posty5 Trigger crea y verifica el endpoint por ti. n8n Posty5 Trigger