Configuración de webhooks

Un webhook le avisa automáticamente a un sistema externo (tu backend, un LMS, un CRM) cada vez que ocurre un evento sobre tus credenciales digitales — por ejemplo, cuando alguien acepta una credencial — sin que tengas que consultar la API de Acreditta periódicamente para saberlo.

Dónde configurarlos

  1. Ve a Configuración → Integraciones → API.
  2. Entra a la pestaña Webhooks.

🔎 Fíjate en: esto está en la pestaña API, no en Herramientas externas — esa otra sección es para integraciones de inicio de sesión y LMS (Microsoft, Google, Moodle, Canvas, etc.), un tema distinto.

⚠️ Importante: los webhooks requieren un plan que incluya esta capacidad. Si tu organización no la tiene, cualquier llamada a la API de webhooks responde 400 y esta pestaña se reemplaza por un aviso para mejorar tu plan. Ver Planes y límites.

Si no tienes ninguno configurado, verás el mensaje “No hay webhooks configurados”. Haz clic en + Nuevo Webhook para crear el primero.

Crear un webhook

Completa:

  • URL del Endpoint (Servicio Web): la dirección de tu sistema que va a recibir la notificación. Es obligatoria.
  • Tipo de autenticación: cómo va a validar tu backend que la notificación realmente viene de Acreditta.
  • Eventos: qué vas a escuchar. Debes marcar al menos uno.

Tipos de autenticación

  • Firma HMAC (Recomendado): Acreditta genera un Secret Key al guardar el webhook, que debes usar en tu backend para validar que cada notificación viene firmada correctamente. Es la opción más segura.
  • Bearer Token: autenticación por token en el encabezado de la solicitud.
  • Basic Auth: usuario y contraseña.
  • Sin autenticación: el endpoint recibe la notificación sin ninguna validación adicional. Solo recomendable si tu endpoint no es públicamente accesible o ya lo proteges por otro medio.

⚠️ Importante: con Firma HMAC, Acreditta firma cada notificación con un Secret Key propio de ese webhook (verás la firma en el encabezado X-Hub-Signature-256 de cada solicitud). Ese es el valor que tu backend necesita para validar la autenticidad de cada notificación — consérvalo en un lugar seguro.

Eventos disponibles

Los eventos están agrupados en dos bloques, y puedes marcar tantos como necesites (o usar “Marcar todos” en cada bloque):

Credenciales:
– Aceptada
– Pendiente
– Fallida
– Revocada
– Expirada
– Versionada

Emisiones en lote:
– Iniciada — el lote de emisiones inicia el procesamiento.
– Completada — el lote de emisiones culmina el procesamiento y reporta el estatus de los envíos.

Haz clic en Guardar Webhook para terminar.

Después de guardarlo

El webhook queda en la lista con su URL, el tipo de autenticación y los eventos suscritos:

🔎 Fíjate en: el webhook se crea con estatus Inactivo. Revisa este estado en la lista antes de darlo por configurado.

Desde los íconos de esa misma fila puedes editar la configuración, probar el webhook, activarlo o desactivarlo, y eliminarlo.

Probar el webhook

Antes de depender de un webhook en producción, puedes disparar una notificación de prueba contra tu endpoint desde el ícono correspondiente en la fila. Acreditta te muestra el detalle completo de la petición enviada y de la respuesta recibida (o el error, si tu endpoint no respondió):

  • URL del endpoint y UUID del webhook que se está probando.
  • Cabeceras (Headers) de la petición, incluida la firma X-Hub-Signature-256 cuando usas Firma HMAC.
  • Cuerpo (Body) de la petición — por ejemplo, para el evento “Pendiente”:
{
  "scope": "credentials",
  "subscope": "status_pending",
  "timestamp": "2026-09-04T23:18:17.834069+00:00",
  "data": {
    "badge_uuid": "73b127b1-e913-40c4-abd7-3b85453d1d76",
    "new_status": "pending",
    "previous_status": "generating"
  }
}
  • Detalle de la respuesta de tu servidor, o el mensaje de error si no fue posible conectarse (por ejemplo, si el dominio no existe o no responde).

🔎 Fíjate en: esta prueba es la forma más rápida de confirmar que tu backend recibe y valida correctamente la firma antes de activar el webhook en serio.

Resiliencia de la entrega

Diseña tu backend asumiendo que una notificación puede no llegar — por ejemplo, si tu endpoint está caído en el momento exacto en que ocurre el evento. No asumas que Acreditta va a reintentar automáticamente una entrega fallida; si tu integración depende de no perder ningún evento, complementa los webhooks con una consulta periódica a la API (por ejemplo, /report/credential/status) para reconciliar el estado real de tus credenciales.

🔎 Fíjate en: si tienes dudas sobre el comportamiento exacto de reintentos para tu caso, escríbenos a tech@acreditta.com antes de construir tu integración asumiendo un número específico de reintentos.


CONTENIDO

Powered By EazyDocs