Webhooks

Descripció general

Els webhooks et permeten rebre notificacions HTTP POST quan es produeixen esdeveniments al teu compte de Holded, com la creació d'una nova factura o la recepció d'un pagament.

Configurar webhooks

Configura els webhooks al teu panell de Holded a Configuració > Webhooks. Necessitaràs proporcionar:

• Una URL HTTPS accessible públicament
• Els esdeveniments als quals vols subscriure't

Capçaleres comunes

Cada petició de webhook inclou aquestes capçaleres:

Esdeveniments disponibles

Els webhooks estan disponibles per als següents grups d'esdeveniments. Fes clic en un grup per veure els seus esdeveniments i detalls del payload.

Verificar webhooks

Cada petició de webhook inclou una capçalera de signatura (x-holded-webhook-signature) que hauries de verificar per confirmar que la petició prové de Holded. La signatura és un resum hexadecimal HMAC-SHA256 del cos en brut de la petició, signat amb el teu secret de webhook i amb el prefix sha256=.

const crypto = require('crypto');

// Use the raw request body, not the parsed JSON object
app.post('/holded-webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const secret = process.env.HOLDED_WEBHOOK_SECRET; // whsec_...

  // The header arrives with a "sha256=" prefix; strip it before comparing
  const received = (req.header('x-holded-webhook-signature') || '').replace(/^sha256=/, '');

  const expected = crypto.createHmac('sha256', secret).update(req.body).digest('hex');

  const valid = received.length === expected.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received));
  if (!valid) return res.status(401).send('Invalid signature');

  const event = req.header('x-holded-webhook-event');
  const data = JSON.parse(req.body.toString('utf8'));

  // ... process the event and acknowledge
  res.sendStatus(200);
});

Resposta esperada

El teu endpoint ha de retornar qualsevol codi d'estat 2xx per confirmar la recepció. Si no rebem una resposta 2xx, reintentarem el lliurament amb backoff exponencial.