Webhooks

Un webhook es una dirección tuya —una URL HTTPS de tu servidor— que Dardo llama cuando pasa algo en tu programa de fidelidad. No consultás vos: te avisan.

Cuándo conviene un webhook y cuándo la API

La página principal de la API ya lo adelanta, y vale insistir porque es la decisión que más tiempo ahorra en una integración:

Para un punto de venta, los webhooks resuelven el sentido inverso al de acreditar una compra: Dardo → tu sistema. Sirven, por ejemplo, para enterarte de que un cliente instaló su tarjeta y darle el alta en tu CRM, para registrar un escaneo en el salón, o para que la pantalla del cajero muestre que el cliente que está pagando acaba de habilitar un beneficio. Todo eso sin que tu sistema tenga que preguntar nada.

Dar de alta un webhook

Se puede desde el panel, en Configuración → Webhooks, o por API.

POST https://api.dardo.ai/api/v2/webhooks

Cuerpo del pedido

curl -X POST 'https://api.dardo.ai/api/v2/webhooks' \
  -H 'X-API-Key: TU_CLAVE_API' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://tu-sistema.com/webhooks/dardo",
    "events": ["CardIssuedEvent"]
  }'

Respuesta

Un 200 con el envelope estándar y, adentro de data, la suscripción creada:

{
  "responseId": "3f1a8b04-6d27-4c9e-9a15-2b8e7c04d913",
  "createdAt": "2026-09-07T18:22:04-03:00",
  "code": 200,
  "data": {
    "id": 1,
    "url": "https://tu-sistema.com/webhooks/dardo",
    "events": ["CardIssuedEvent"]
  }
}

Guardate el data.id: es lo único con lo que después vas a poder dar de baja la suscripción.

Dar de baja un webhook

DELETE https://api.dardo.ai/api/v2/webhooks/{id}

El {id} es el que te devolvió el alta.

curl -X DELETE 'https://api.dardo.ai/api/v2/webhooks/1' \
  -H 'X-API-Key: TU_CLAVE_API'

Responde 200 con el envelope estándar. También acá el único error declarado es un 400, y también tapa dos causas: webhook inexistente, o webhooks no disponibles en la suscripción actual.

Cómo es el cuerpo de cada entrega

Toda entrega llega con la misma forma:

{
  "timestamp": "2026-09-07T18:22:04-03:00",
  "event": "CardIssuedEvent",
  "data": { },
  "is_sandbox": false
}

Nombres de evento

La lista de nombres válidos para events no está en la especificación: se consulta en vivo.

Verificar la firma

Esto es lo más importante de la página. Tu endpoint de webhooks es una URL pública: cualquiera que la descubra puede mandarle un JSON inventado. Si le creés sin verificar, le estás dando a un desconocido la capacidad de escribir en tu sistema.

Cada entrega viaja con un header X-Signature:

X-Signature = hash_hmac('sha256', <cuerpo crudo>, <clave API de la cuenta que recibe>)

Es hexadecimal en minúscula, 64 caracteres. Tres reglas que no se negocian:

Ejemplo en Node.js

Con Express, quedándose con el cuerpo crudo:

import express from 'express';
import crypto from 'node:crypto';

const app = express();
const API_KEY = process.env.DARDO_API_KEY;

// Guardamos el body sin procesar. Sin esto no se puede verificar nada.
app.use('/webhooks/dardo', express.raw({ type: 'application/json' }));

function firmaValida(rawBody, firmaRecibida) {
  if (!firmaRecibida) return false; // header ausente: no confiamos

  const esperada = crypto
    .createHmac('sha256', API_KEY)
    .update(rawBody)          // Buffer crudo, sin re-serializar
    .digest('hex');           // hex minúscula, 64 chars

  const a = Buffer.from(esperada, 'utf8');
  const b = Buffer.from(firmaRecibida, 'utf8');
  if (a.length !== b.length) return false;

  return crypto.timingSafeEqual(a, b);
}

app.post('/webhooks/dardo', (req, res) => {
  if (!firmaValida(req.body, req.get('X-Signature'))) {
    return res.status(401).send('firma inválida');
  }

  const evento = JSON.parse(req.body.toString('utf8'));
  // { timestamp, event, data, is_sandbox }

  // Respondemos primero, procesamos después.
  res.status(200).send('ok');
  encolar(evento);
});

app.listen(3000);

Cómo tiene que comportarse tu receptor

Tres reglas que te cubren igual, y que son buena práctica en cualquier integración por webhooks:

• Hacé el receptor idempotente. Procesar la misma entrega dos veces tiene que dar el mismo resultado que procesarla una. Guardá una marca de lo ya procesado —el event más el identificador que venga en data— y descartá los repetidos.
• Respondé rápido y trabajá después. Verificá la firma, encolá el evento, devolvé 200. No hagas la consulta a tu base, el envío del mail y la impresión del ticket dentro del pedido HTTP. Si tardás, arriesgás que la entrega se corte del otro lado.
• No asumas orden. Si tu lógica depende de que un evento llegue antes que otro, reconstruí el estado consultando la API en vez de encadenar webhooks. El timestamp de cada entrega te dice cuándo ocurrió cada cosa.

Ver también