Documentation Index
Fetch the complete documentation index at: /llms.txt
Use this file to discover all available pages before exploring further.
Assinatura HMAC nos webhooks da API Core
X-Webhook-Signature antes de aplicar efeitos colaterais no seu sistema.
secret (whsec_...) retornado em Criar webhook. O header vem no formato sha256=<hex>.
express.json() global altera o corpo. Na rota do webhook, use buffer bruto — por exemplo express.raw({ type: 'application/json' }).import express from 'express';
import crypto from 'node:crypto';
function coreWebhookSignatureValid(bodyUtf8, signatureHeader, secret) {
if (!signatureHeader || !secret) return false;
const expectedPrefix = 'sha256=';
const headerValue = String(signatureHeader).trim();
if (!headerValue.startsWith(expectedPrefix)) return false;
const receivedHex = headerValue.slice(expectedPrefix.length);
const computedHex = crypto.createHmac('sha256', secret).update(bodyUtf8, 'utf8').digest('hex');
const left = Buffer.from(computedHex, 'utf8');
const right = Buffer.from(receivedHex, 'utf8');
if (left.length !== right.length) return false;
return crypto.timingSafeEqual(left, right);
}
const app = express();
app.post(
'/webhooks/upag-core',
express.raw({ type: 'application/json' }),
async (req, res) => {
const bodyUtf8 = req.body.toString('utf8');
const signatureHeader = req.headers['x-webhook-signature'];
const secret = process.env.UPAG_CORE_WEBHOOK_SECRET;
if (!coreWebhookSignatureValid(bodyUtf8, signatureHeader, secret)) {
return res.status(401).send('assinatura inválida');
}
const payload = JSON.parse(bodyUtf8);
await handleCoreWebhook(payload);
return res.status(200).send('ok');
},
);
X-Webhook-Id, X-Webhook-Event, além de cabeçalhos customizados definidos no cadastro do webhook.
id da entrega (UUID no envelope) ou ${event}:${data.id} antes de side effects.
async function handleCoreWebhook(payload) {
const deliveryId = payload.id;
if (deliveryId && (await db.webhookDedupe.exists(deliveryId))) return;
await dispatch(payload);
if (deliveryId) await db.webhookDedupe.put(deliveryId);
}
| Item | Ação |
|---|---|
| URL | TLS em produção |
| Secret | Só em variável de ambiente |
| Assinatura | Antes de dispatch |
| Resposta HTTP | 2xx após fila ou commit |
| Payload | Leia só os campos que você usa |