Para desarrolladores · Webhooks
Webhooks
Notificaciones automáticas
Cuando un cliente sube un comprobante, Verifika analiza la imagen y envía un POST firmado a tu servidor con el resultado. Sin polling — te avisamos nosotros.
HMAC-SHA256 firmado
Configurable en el dashboard
Botón de prueba incluido
Configuración
1
Agrega tu URL en el dashboard
Dashboard → sección Webhooks. Ingresa la URL de tu endpoint y guarda. Verifika genera un secret único automáticamente.
Ir al dashboard →2
Copia el secret
Está en la misma sección, con botón de revelar/copiar. Guárdalo como variable de entorno en tu servidor.
3
Verifica la firma en cada request
Cada POST incluye X-Verifika-Signature: sha256=… — HMAC del body con tu secret.
Headers del request entrante
X-Verifika-SignatureFirma HMAC-SHA256. Formato
sha256=abcdef…X-Verifika-Event
comprobante.analizado o testContent-Type
application/jsonPayload — comprobante.analizado
payload.json
{
"event": "comprobante.analizado",
"timestamp": "2026-06-25T20:15:32.000Z",
"data": {
"veredicto": "LEGITIMO", // LEGITIMO | SOSPECHOSO | INCIERTO
"puntaje_autenticidad": 94,
"accion_recomendada": "PRE_APROBADO", // PRE_APROBADO | RECHAZADO | RETENER
"banco": "Banco Agrícola",
"monto": "$45.00",
"transfer_code": "ABC123",
"submission_id": "uuid-de-la-entrega",
"pay_link_id": "uuid-del-cobro",
"scan_id": "uuid-del-scan"
}
}Verificar la firma
Node.js
app.post('/webhook/verifika', express.raw({ type: '*/*' }), (req, res) => {
const sig = req.headers['x-verifika-signature'];
const expected = 'sha256=' + crypto
.createHmac('sha256', process.env.VERIFIKA_SECRET)
.update(req.body) // body como raw Buffer
.digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig)))
return res.status(401).end();
const { data } = JSON.parse(req.body);
if (data.accion_recomendada === 'PRE_APROBADO') {
// confirmar pedido
}
res.json({ ok: true });
});PHP
<?php
$body = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $body, getenv('VERIFIKA_SECRET'));
if (!hash_equals($expected, $_SERVER['HTTP_X_VERIFIKA_SIGNATURE'])) {
http_response_code(401); exit;
}
$payload = json_decode($body, true);
if ($payload['data']['accion_recomendada'] === 'PRE_APROBADO') {
// confirmar pedido
}Notas importantes
- Responde
2xxen menos de 8 segundos o el request falla. - Lee el body como raw bytes antes de parsear JSON — el HMAC se calcula sobre el texto crudo.
- Usa
timingSafeEqual/hash_equalspara prevenir timing attacks. - El evento
testse dispara desde el dashboard → Webhooks → botón "Enviar prueba".