Saltar al contenido principal
Tú administras tus suscripciones desde Pruff, en Configuración → Otros → Webhooks. Cada suscripción es una URL de destino con los eventos que quieres recibir en ella.

Permisos

Los administradores tienen ambos permisos. La pestaña Webhooks solo aparece para los usuarios que pueden ver webhooks. Si no la ves, pide a un administrador de tu empresa que te asigne el permiso a través de un rol.

Crear una suscripción

1

Abre Configurar webhook

En Configuración → Otros → Webhooks, elige Configurar webhook (o Agregar webhook si ya tienes una suscripción).
2

Indica la URL de tu endpoint

Es la URL que recibirá los eventos. Pruff la valida antes de guardarla (ver las reglas más abajo).
3

Elige los eventos

Selecciona al menos un evento de los disponibles. Puedes elegir hasta 20.
4

Opcional: agrega un header de autenticación

Si tu endpoint exige su propio header además de la firma, escríbelo con el formato Nombre: valor, por ejemplo Authorization: Bearer <tu-token>.
5

Guarda el secreto

Al crear la suscripción, Pruff muestra el secreto de firma. Cópialo y guárdalo en tu sistema: solo se muestra una vez.
Una suscripción nueva queda activa de inmediato y recibe todos sus eventos en la URL que indicaste, sin agregarle el path del evento. Distingue cada evento con el header X-Webhook-Event.

Reglas de la URL

  • Debe usar https.
  • No puede tener más de 191 caracteres, ni usuario y contraseña, ni fragmento (#).
  • Su dominio debe resolverse y apuntar a una dirección pública. Pruff rechaza direcciones privadas o reservadas, como localhost, los dominios .local e .internal, y las IP de redes internas.
  • Pruff no sigue redirecciones: indica la URL final (ver Entregas y reintentos).
  • No puedes tener dos suscripciones con la misma URL. Si ya existe una, edítala.

Reglas del header de autenticación

  • El nombre admite letras, números y los símbolos ! # $ % & ' * + . ^ _ ` | ~ -, hasta 64 caracteres.
  • El valor admite caracteres ASCII imprimibles, hasta 77 caracteres.
  • No puedes usar los nombres que Pruff ya envía: Content-Type, Content-Length, Host, User-Agent ni ninguno que empiece con X-Webhook-.
El header de idempotencia no se configura desde esta pantalla. Si lo necesitas, solicítalo a tu contacto en Pruff.

Editar una suscripción

Con el permiso webhooks_manage puedes cambiar, en una suscripción activa:
  • La URL. Los eventos siguientes se envían a la URL nueva, con las mismas reglas de una URL nueva.
  • Los eventos. Al quitar un evento, Pruff deja de enviarlo a esa URL. Al volver a agregarlo, se reactiva.
  • El header de autenticación. Puedes cambiarlo o quitarlo.
El secreto no cambia al editar. Para cambiarlo, regenéralo.
Al cambiar la URL, los reintentos de eventos anteriores siguen yendo a la URL vieja. Si migras a otro endpoint, mantén el anterior activo hasta que terminen los reintentos pendientes.
Pruff puede dejar una suscripción inactiva. En ese caso no se envían eventos a su URL y no puedes editarla ni probarla desde la pantalla: escribe a tu contacto en Pruff para reactivarla.

Secreto de firma

Pruff firma cada entrega con el secreto de tu suscripción (ver Headers y firma). El secreto es una cadena hexadecimal de 64 caracteres, propia de cada suscripción.
  • Se muestra una sola vez, al crear la suscripción y cada vez que lo regeneras. Después no puedes volver a verlo.
  • Puedes regenerarlo con Regenerar secreto cuando lo pierdas o sospeches que se filtró. Se regenera para todos los eventos de la suscripción.
  • Pruff pide confirmación antes de regenerarlo.
  • El secreto anterior deja de funcionar de inmediato, sin período de gracia. Las entregas nuevas se firman con el secreto nuevo, así que actualízalo en tu sistema apenas lo regeneres.
Los reintentos que ya estaban en cola conservan la firma y los headers originales, hechos con el secreto anterior (ver Entregas y reintentos). Si regeneras el secreto mientras hay reintentos pendientes, esas entregas pueden fallar la validación con el secreto nuevo.

Siguiente paso

Cuando tengas el secreto configurado en tu sistema, envía un evento de prueba para confirmar que tu endpoint responde 2xx.